So binden Sie ein Live-Goldpreis-Widget in Ihre Website ein

Was Sie einbetten

Ein MetalAPI-Widget ist eine kleine Preistafel, die MetalAPI für Sie hostet. Sie konfigurieren es einmal im Dashboard, fügen ein zweizeiliges Snippet in Ihre Seite ein, und Besucher sehen aktuelle Preise für Gold, Silber, Platin, Palladium, Industriemetalle, Energie, Währungen oder Krypto. Das Widget wird in einem iframe dargestellt, das von metalapi.com ausgeliefert wird. Sie müssen keinen Backend-Code schreiben, kein API-Schlüssel steht in Ihrem HTML, und wenn sich Preise bewegen, müssen Sie auf Ihrer Seite nichts aktualisieren.

Damit ist ein Widget die schnellste Lösung für Content-Websites, Schmuck- und Edelmetallhändler, Nachrichtenseiten und Blogs, die den aktuellen Preis neben ihren eigenen Inhalten zeigen möchten. Brauchen Sie den Preis in Ihrem eigenen Markup oder in einer Berechnung, passt die REST-API besser. Der letzte Abschnitt dieses Artikels behandelt diesen Fall.

Widget-Traffic wird über den Widget-Endpunkt von MetalAPI ausgeliefert, nicht über Ihren API-Schlüssel. Seitenaufrufe verbrauchen daher nichts von Ihrem Monatskontingent. Ihr Tarif bestimmt, wie viele Widgets Sie speichern können und wie aktuell deren Preise sind; beides wird unten erklärt.

Das Widget im Dashboard erstellen

Widgets sind in jedem Tarif enthalten, auch im Free-Tarif. Erstellen Sie ein Konto, öffnen Sie im Dashboard Widgets und klicken Sie auf New widget. Der Builder zeigt neben dem Formular eine Live-Vorschau, sodass Sie Optionen vor dem Speichern ausprobieren können:

Zwei Details übersieht man leicht. Belassen Sie die Einheit bei Feinunze, werden Industriemetalle stattdessen in ihrer marktüblichen Einheit angezeigt: Kupfer erscheint pro Pfund, Gold bleibt pro Feinunze. Und eine Einheit in Gramm oder Kilogramm rechnet nur Metalle um: Währungen, Energie und Krypto behalten ihre eigenen Einheiten. Wenn Sie unsicher sind, welche Gewichtseinheit Ihre Besucher erwarten, erklärt der Leitfaden zur Einheitenumrechnung die Unterschiede.

Beim Speichern erhält das Widget eine öffentliche ID wie w_abc123. Der Einbettungscode verweist nur auf diese ID; die Konfiguration bleibt auf den Servern von MetalAPI. Ändern Sie später Symbole, Farben oder das Layout, zeigt jede Seite, die das Widget einbettet, beim nächsten Laden die neue Version, ohne dass Sie das Snippet auf Ihrer Website ändern müssen. Die Widget-Liste bietet außerdem einen Live-Schalter, mit dem Sie ein Widget offline nehmen können, ohne es zu löschen, sowie einen Aufrufzähler pro Widget.

Der Einbettungscode Zeile für Zeile

Nach dem Speichern zeigt der Builder den Einbettungscode:

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

Das Skript ist ein kleiner Loader, vor der Komprimierung etwa 4 KB groß. Er liest data-widget, sucht das Element mit der id metalapi-widget-<id> und füllt es mit einem iframe, das https://metalapi.com/embed/<id> lädt. Fehlt der Container, erstellt der Loader direkt vor dem Script-Tag einen. Das Widget im Frame meldet seine Höhe per postMessage, und der Loader passt die Höhe des iframes daran an. So zeigt eine Tabelle, die von drei auf sechs Zeilen wächst, nie eine Scrollleiste.

Der Loader läuft nur einmal pro Seite, auch wenn das Script-Tag mehrfach vorkommt. Um mehrere Widgets auf einer Seite anzuzeigen, binden Sie das Skript ein einziges Mal ein und kennzeichnen jeden Container mit einem data-metalapi-widget-Attribut statt einer 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>

Der Loader sucht diese Container einmal, sobald die Seite geladen ist. Container, die clientseitiges JavaScript später hinzufügt, etwa nach einem Routenwechsel in einer Single-Page-App, sieht er nicht. In diesem Fall oder wenn Sie überhaupt keine Skripte einfügen können, betten Sie den Frame direkt ein:

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

Ohne den Loader kann das iframe seine Größe nicht selbst anpassen. Geben Sie ihm daher eine Höhe, die zum gewählten Layout passt. Seiten, die noch das ältere Snippet new MetalAPIWidget({...}) aus dem früheren Widget-Generator verwenden, funktionieren weiter: Gespeicherte Widgets werden anhand ihrer ID dargestellt, und ein in einem alten Snippet verbliebener API-Schlüssel wird ignoriert.

Einfaches HTML, WordPress und Shopify

Einfaches HTML. Fügen Sie das Snippet dort ein, wo das Widget erscheinen soll, zum Beispiel in einer Seitenleiste oder oben auf einer Preisseite. Dank des Attributs async blockiert der Loader beim Herunterladen nie den Rest der Seite.

WordPress. Fügen Sie im Block-Editor einen Block Individuelles HTML (Custom HTML) hinzu und setzen Sie das Snippet ein. Damit das Widget auf jeder Seite erscheint, legen Sie es in ein HTML-Widget in einem Widget-Bereich der Seitenleiste oder des Footers oder in die Template-Dateien Ihres Themes. Manche Installationen, etwa Multisite-Netzwerke oder eingeschränkte Hosting-Tarife, entfernen <script>-Tags aus Inhalten. Erscheint das Widget nach dem Veröffentlichen nicht, sehen Sie sich den Quelltext der Seite an. Fehlt das Script-Tag, verwenden Sie die iframe-Variante, die ohne Skript auskommt.

Shopify. Fügen Sie im Theme-Editor (Onlineshop → Themes → Anpassen, im englischen Admin Online Store → Themes → Customize) der Vorlage, in die das Widget gehört, einen Abschnitt oder Block Benutzerdefiniertes Liquid (Custom Liquid) hinzu und setzen Sie das Snippet ein. Um es nur auf Produktseiten anzuzeigen, fügen Sie den Block der Produktvorlage hinzu. Sie können das Snippet auch direkt in eine Abschnittsdatei einfügen, wenn Sie den Theme-Code bearbeiten.

Andere Website-Baukästen. Baukästen mit einem HTML- oder Embed-Element funktionieren genauso, etwa das Code-Embed von Webflow oder ein Code-Block in Squarespace. Manche Baukästen packen eigenes HTML in ein zusätzliches iframe, durch das die automatische Größenanpassung nicht hindurchreicht. Geben Sie dem Embed-Element in diesem Fall eine feste Höhe.

Tariflimits, Aktualität und Branding

Ein gespeichertes Widget zeigt Preise so aktuell, wie der Tarif seines Besitzers es erlaubt, und fragt selbstständig neue Daten ab. Das Abfrageintervall folgt dem Aktualisierungsintervall des Tarifs, ist aber nie kürzer als 30 Sekunden und nie länger als 15 Minuten:

Im Free- und im Lite-Tarif prüft das Widget häufiger auf neue Daten, als sich die Preise ändern, und übernimmt so jede Aktualisierung ohne Neuladen. Jedes Widget zeigt unten die Zeit seiner Daten in UTC an, sodass Besucher sehen, wie aktuell die Preise sind. Die vollständige Funktionsliste pro Tarif finden Sie auf der Preisseite.

Performance und Layoutverschiebungen

Ein Widget belastet eine Seite kaum:

• Nicht blockierendes Skript. Der Loader wird mit async geladen und mit einer Browser-Cache-Dauer von einer Stunde ausgeliefert, sodass wiederkehrende Besucher ihn meist nicht erneut herunterladen.
• Lazy Loading für Frames. Der Loader erstellt das iframe mit loading="lazy", sodass ein Widget weit unten auf der Seite erst geladen wird, wenn der Besucher in seine Nähe scrollt.
• Isolation. Das Widget läuft in einem eigenen Frame. Ihre Stylesheets können es nicht beschädigen, und sein Code kann Ihre Seite nicht verändern.
• Seiten-Caching ist unbedenklich. Das Snippet ändert sich nie, und die Preise werden innerhalb des Frames geladen. WordPress-Caching-Plugins, das CDN von Shopify oder jeder andere Full-Page-Cache können Ihr HTML beliebig lange vorhalten, ohne den Preis einzufrieren.

Planen müssen Sie nur für Layoutverschiebungen. Der Frame startet mit einer Höhe von 120 Pixeln und wächst dann auf die tatsächliche Höhe des Widgets, was den Inhalt darunter nach unten schieben kann. Reservieren Sie den Platz vorab mit einer Mindesthöhe am Container und verwenden Sie dafür die Höhe, die Sie in der Vorschau des Builders sehen:

<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>

Ein Ticker braucht deutlich weniger Platz als eine Tabelle mit acht Metallen. Verwenden Sie daher pro Widget einen eigenen Wert statt eines websiteweiten Standardwerts.

Wann Sie stattdessen die API nutzen sollten

Ein Widget ist eine fertige Komponente. Verwenden Sie die API, wenn Sie etwas brauchen, das ein Widget nicht leistet:

• Preise in Ihrem eigenen HTML. Text in einem iframe gehört zu einem anderen Dokument, daher werten Suchmaschinen ihn möglicherweise nicht als Teil Ihrer Seite. Soll der Preis Teil Ihres Seiteninhalts sein, rendern Sie ihn auf dem Server.
• Ihr eigenes Design. Widgets bieten vier Layouts, ein Theme und eine Akzentfarbe. Für alles darüber hinaus schreiben Sie Ihr eigenes Markup.
• Berechnungen. Produktpreise nach Gewicht und Feingehalt, Ankaufsangebote und Umrechnungen gehören auf Ihren Server. Das Tutorial zum Schmuckpreisrechner zeigt ein Beispiel.
• Daten in Ihrer Anwendung. Charts, Historie und gespeicherte Preise benötigen die Endpunkte für historische Kurse und Zeiträume, die in der API-Dokumentation beschrieben sind.

Rufen Sie die API von Ihrem Server auf und cachen Sie jede Antwort für das Aktualisierungsintervall Ihres Tarifs. In WordPress erledigt ein Shortcode mit Transient-Cache beides in wenigen Zeilen:

<?php
// In 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); // Aktualisierungsintervall Ihres Tarifs
    }

    $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))
    );
});

Verwenden Sie ihn in jedem Beitrag und auf jeder Seite als [gold_price currency="EUR" unit="gram"]. Der Schlüssel in der Antwort besteht aus der Basiswährung, gefolgt vom Symbol; rates.EURXAU ist also der Preis eines Gramms Gold in Euro. Jeder Cache-Miss kostet eine Anfrage. Ein Transient mit 10 Minuten verbraucht daher höchstens etwa 4.500 Anfragen im Monat für jede angezeigte Kombination aus Währung und Einheit, was in den Standard-Tarif passt.

Wenn Sie die API stattdessen aus dem Browser aufrufen müssen, beschränken Sie den Schlüssel vorher auf Ihre eigenen Domains, wie in der Anleitung zur Authentifizierung beschrieben. Für eine reine Preisanzeige bleibt das Widget jedoch die einfachere Wahl: kein Schlüssel, kein Cache zu verwalten und nichts zu pflegen, wenn Sie später Symbole ändern.