Ajouter un widget de prix de l'or en direct à votre site web

Ce que vous intégrez

Un widget MetalAPI est un petit tableau de prix que MetalAPI héberge pour vous. Vous le configurez une fois dans le tableau de bord, collez un extrait de deux lignes dans votre page, et vos visiteurs voient les prix actuels de l'or, de l'argent, du platine, du palladium, des métaux industriels, de l'énergie, des devises ou des cryptos. Le widget s'affiche dans une iframe servie depuis metalapi.com. Aucun code backend à écrire, aucune clé API dans votre HTML, et rien à mettre à jour de votre côté quand les prix bougent.

Le widget est donc l'option la plus rapide pour les sites de contenu, les bijouteries et les boutiques de métaux précieux, les sites d'actualité et les blogs qui veulent afficher le prix actuel à côté de leur propre contenu. Si vous avez besoin du prix dans votre propre balisage ou dans un calcul, l'API REST convient mieux. La dernière section de cet article traite de ce cas.

Le trafic des widgets est servi par l'endpoint des widgets de MetalAPI, et non via votre clé API : les pages vues ne consomment donc pas votre quota mensuel de requêtes. Votre plan détermine le nombre de widgets que vous pouvez enregistrer et la fraîcheur de leurs prix ; ces deux points sont détaillés plus bas.

Créer le widget dans le tableau de bord

Les widgets sont inclus dans tous les plans, Free compris. Créez un compte, ouvrez Widgets dans le tableau de bord et cliquez sur New widget. L'éditeur affiche un aperçu en direct à côté du formulaire, pour que vous puissiez essayer les options avant d'enregistrer :

Deux détails passent facilement inaperçus. Si vous laissez l'unité sur l'once troy, les métaux industriels s'affichent plutôt dans leur unité de marché habituelle : le cuivre apparaît ainsi à la livre, tandis que l'or reste à l'once troy. Et une unité en grammes ou en kilogrammes ne convertit que les métaux : les devises, l'énergie et les cryptos conservent leurs propres unités. Si vous ne savez pas quelle unité de poids vos visiteurs attendent, le guide de conversion des unités explique les différences.

L'enregistrement attribue au widget un identifiant public, par exemple w_abc123. Le code d'intégration ne fait référence qu'à cet identifiant ; la configuration reste sur les serveurs de MetalAPI. Lorsque vous modifiez ensuite les symboles, les couleurs ou la mise en page, toutes les pages qui intègrent le widget affichent la nouvelle version à leur prochain chargement, sans aucune modification de l'extrait sur votre site. La liste des widgets propose aussi un interrupteur Live pour mettre un widget hors ligne sans le supprimer, ainsi qu'un compteur de vues par widget.

Le code d'intégration, ligne par ligne

Après l'enregistrement, l'éditeur affiche le code d'intégration :

<div id="metalapi-widget-w_abc123"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

Le script est un petit chargeur d'environ 4 Ko avant compression. Il lit data-widget, cherche l'élément dont l'id est metalapi-widget-<id> et y insère une iframe qui charge https://metalapi.com/embed/<id>. Si le conteneur est absent, le chargeur en crée un juste avant la balise script. Le widget, à l'intérieur du cadre, communique sa hauteur avec postMessage, et le chargeur redimensionne l'iframe en conséquence : un tableau qui passe de trois à six lignes n'affiche donc jamais de barre de défilement.

Le chargeur ne s'exécute qu'une fois par page, même si la balise script apparaît plusieurs fois. Pour afficher plusieurs widgets sur une même page, incluez le script une seule fois et marquez chaque conteneur avec un attribut data-metalapi-widget au lieu d'un id :

<div data-metalapi-widget="w_abc123"></div>
<div data-metalapi-widget="w_def456"></div>

<script src="https://metalapi.com/js/widget.js" async></script>

Le chargeur recherche ces conteneurs une seule fois, au chargement de la page. Il ne voit pas les conteneurs ajoutés plus tard par du JavaScript côté client, par exemple après un changement de route dans une application monopage. Dans ce cas, ou lorsque vous ne pouvez pas du tout ajouter de script, intégrez directement le cadre :

<iframe
  src="https://metalapi.com/embed/w_abc123"
  title="Live gold price"
  loading="lazy"
  style="border:0;width:100%;height:220px"
></iframe>

Sans le chargeur, l'iframe ne peut pas se redimensionner : donnez-lui donc une hauteur adaptée à la mise en page choisie. Les pages qui utilisent encore l'ancien extrait new MetalAPIWidget({...}) de l'ancien générateur de widgets continuent de fonctionner : les widgets enregistrés s'affichent d'après leur identifiant, et toute clé API restée dans un ancien extrait est ignorée.

HTML pur, WordPress et Shopify

HTML pur. Collez l'extrait à l'endroit où le widget doit apparaître, par exemple dans une barre latérale ou en haut d'une page de prix. Grâce à l'attribut async, le chargeur ne bloque jamais le reste de la page pendant son téléchargement.

WordPress. Dans l'éditeur de blocs, ajoutez un bloc HTML personnalisé (Custom HTML) et collez l'extrait. Pour afficher le widget sur toutes les pages, placez-le dans un widget HTML personnalisé, dans une zone de widgets de la barre latérale ou du pied de page, ou dans les fichiers de modèle de votre thème. Certaines configurations, comme les réseaux multisites ou les offres d'hébergement restreintes, suppriment les balises <script> du contenu. Si le widget n'apparaît pas après la publication, affichez le code source de la page. Si la balise script est absente, utilisez la version iframe, qui ne nécessite aucun script.

Shopify. Dans l'éditeur de thème (Boutique en ligne → Thèmes → Personnaliser), ajoutez une section ou un bloc Liquid personnalisé (Custom Liquid) au modèle où le widget doit figurer, puis collez l'extrait. Pour ne l'afficher que sur les pages produit, ajoutez le bloc au modèle de produit. Vous pouvez aussi placer l'extrait directement dans un fichier de section lorsque vous modifiez le code du thème.

Autres créateurs de sites. Les créateurs qui proposent un élément HTML ou d'intégration fonctionnent de la même façon, par exemple l'élément code embed de Webflow ou un bloc de code Squarespace. Certains créateurs enveloppent le HTML personnalisé dans leur propre iframe, et le redimensionnement automatique ne peut pas la traverser. Dans ce cas, donnez une hauteur fixe à l'élément d'intégration.

Limites des plans, fraîcheur et mention de marque

Un widget enregistré affiche des prix aussi frais que le plan de son propriétaire le permet, et il va chercher lui-même les nouvelles données. Son intervalle d'interrogation suit l'intervalle de mise à jour du plan, mais il n'est jamais inférieur à 30 secondes ni supérieur à 15 minutes :

Sur Free et Lite, le widget vérifie la présence de nouvelles données plus souvent que les prix ne changent : il récupère donc chaque mise à jour sans rechargement. Chaque widget affiche en bas l'heure de ses données en UTC, pour que les visiteurs voient à quel point les prix sont récents. La liste complète des fonctionnalités par plan se trouve sur la page des tarifs.

Performances et décalage de mise en page

Un widget alourdit très peu une page :

• Script non bloquant. Le chargeur est chargé avec async et servi avec un cache navigateur d'une heure : les visiteurs qui reviennent n'ont donc généralement pas à le télécharger à nouveau.
• Cadres différés. Le chargeur crée l'iframe avec loading="lazy" : un widget situé loin dans la page n'est récupéré que lorsque le visiteur s'en approche en faisant défiler.
• Isolation. Le widget s'exécute dans son propre cadre. Vos feuilles de style ne peuvent pas le casser, et son code ne peut pas toucher à votre page.
• La mise en cache des pages ne pose aucun problème. L'extrait ne change jamais et les prix sont chargés à l'intérieur du cadre. Les extensions de cache WordPress, le CDN de Shopify ou tout autre cache de page complète peuvent conserver votre HTML aussi longtemps qu'ils le souhaitent sans figer le prix.

Le seul point à anticiper est le décalage de mise en page. Le cadre démarre à 120 pixels, puis s'agrandit jusqu'à la hauteur réelle du widget, ce qui peut repousser vers le bas le contenu situé en dessous. Réservez l'espace à l'avance avec une hauteur minimale sur le conteneur, en reprenant la hauteur visible dans l'aperçu de l'éditeur :

<div id="metalapi-widget-w_abc123" style="min-height:240px"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

Un bandeau (ticker) occupe bien moins de place qu'un tableau de huit métaux : utilisez donc une valeur propre à chaque widget plutôt qu'une valeur par défaut pour tout le site.

Quand utiliser plutôt l'API

Un widget est un composant fini. Utilisez l'API lorsque vous avez besoin de quelque chose qu'un widget ne fait pas :

• Des prix dans votre propre HTML. Le texte d'une iframe appartient à un autre document : les moteurs de recherche peuvent donc ne pas le considérer comme faisant partie de votre page. Si le prix doit faire partie du contenu de votre page, générez-le côté serveur.
• Votre propre design. Les widgets proposent quatre mises en page, un thème et une couleur d'accent. Au-delà, écrivez votre propre balisage.
• Des calculs. Les prix de produits fondés sur le poids et la pureté, les devis de rachat et les conversions ont leur place sur votre serveur. Le tutoriel du calculateur de prix de bijoux en construit un pas à pas.
• Des données dans votre application. Les graphiques, l'historique et les prix stockés nécessitent les endpoints historical et timeframe décrits dans la documentation de l'API.

Appelez l'API depuis votre serveur et mettez chaque réponse en cache pendant l'intervalle de mise à jour de votre plan. Sur WordPress, un shortcode associé à un cache transient fait les deux en quelques lignes :

<?php
// Dans wp-config.php : define('METALAPI_KEY', 'mk_live_...');
add_shortcode('gold_price', function ($atts) {
    $a = shortcode_atts(['currency' => 'USD', 'unit' => 'troy_oz'], $atts);
    $currency = strtoupper(preg_replace('/[^A-Za-z]/', '', $a['currency']));
    $unit = sanitize_key($a['unit']);
    $cache_key = "metalapi_xau_{$currency}_{$unit}";

    $data = get_transient($cache_key);
    if ($data === false) {
        $url = add_query_arg(
            ['base' => $currency, 'currencies' => 'XAU', 'unit' => $unit],
            'https://metalapi.com/api/v1/latest'
        );
        $res = wp_remote_get($url, ['headers' => ['X-API-Key' => METALAPI_KEY], 'timeout' => 10]);
        if (is_wp_error($res)) return '';
        $data = json_decode(wp_remote_retrieve_body($res), true);
        if (empty($data['success'])) return '';
        set_transient($cache_key, $data, 10 * MINUTE_IN_SECONDS); // l'intervalle de mise à jour de votre plan
    }

    $price = $data['rates'][$currency . 'XAU'] ?? null;
    if ($price === null) return '';
    return sprintf(
        '<span class="gold-price">%s %s / %s</span>',
        esc_html(number_format_i18n($price, 2)),
        esc_html($currency),
        esc_html(str_replace('_', ' ', $unit))
    );
});

Utilisez-le dans n'importe quel article ou page sous la forme [gold_price currency="EUR" unit="gram"]. La clé de la réponse est la devise de base suivie du symbole : rates.EURXAU est donc le prix d'un gramme d'or en euros. Chaque absence dans le cache coûte une requête : un transient de 10 minutes consomme donc au maximum environ 4 500 requêtes par mois pour chaque devise et unité affichées, ce qui tient dans le plan Standard.

Si vous devez plutôt appeler l'API depuis le navigateur, restreignez d'abord la clé à vos propres domaines, comme l'explique le guide d'authentification. Pour un simple affichage de prix, le widget reste toutefois le choix le plus simple : pas de clé, pas de cache à gérer et rien à maintenir lorsque vous changerez de symboles plus tard.