Webサイトに金価格のライブウィジェットを追加する方法

埋め込むものの概要

MetalAPIウィジェットは、MetalAPIがホストする小さな価格ボードです。ダッシュボードで一度設定し、2行のスニペットをページに貼り付けるだけで、訪問者は金、銀、プラチナ、パラジウム、産業用金属、エネルギー、通貨、暗号資産の現在価格を見られるようになります。ウィジェットは、metalapi.comから配信されるiframe内に描画されます。バックエンドのコードを書く必要はなく、HTMLにAPIキーが含まれることもなく、価格が動いても自分の側で更新する必要はありません。

そのため、ウィジェットは、自社のコンテンツの横に現在価格を表示したいコンテンツサイト、ジュエリーや地金の販売店、ニュースページ、ブログにとって最も手早い方法です。自分のマークアップ内や計算で価格を使う必要がある場合は、REST APIのほうが適しています。そのケースは、この記事の最後のセクションで扱います。

ウィジェットのトラフィックは、APIキーを経由せず、MetalAPIのウィジェット用エンドポイントから配信されます。そのため、ページビューが月間リクエストクォータを消費することはありません。保存できるウィジェットの数と価格の鮮度はプランによって決まります。どちらも後述します。

ダッシュボードでウィジェットを作成する

ウィジェットは、Freeを含むすべてのプランで利用できます。アカウントを作成し、ダッシュボードでWidgetsを開いてNew widgetをクリックします。ビルダーにはフォームの横にライブプレビューが表示されるので、保存前にオプションを試せます：

見落としやすい点が2つあります。単位をトロイオンスのままにすると、産業用金属は市場で一般的な単位で表示されます。つまり、金はトロイオンスあたりのままですが、銅はポンドあたりで表示されます。また、グラムやキログラムの単位は金属にのみ適用され、通貨、エネルギー、暗号資産はそれぞれ独自の単位のままです。訪問者がどの重さの単位を想定しているかわからない場合は、単位換算ガイドで違いを確認してください。

保存すると、ウィジェットにw_abc123のような公開IDが付きます。埋め込みコードが参照するのはこのIDだけで、設定はMetalAPIのサーバーに保存されます。後でシンボル、色、レイアウトを変更すると、ウィジェットを埋め込んでいるすべてのページで、次回の読み込み時から新しいバージョンが表示されます。サイト上のスニペットを変更する必要はありません。ウィジェットの一覧には、削除せずにウィジェットを非公開にできるLiveスイッチと、ウィジェットごとの表示回数カウンターもあります。

埋め込みコードを1行ずつ見る

保存すると、ビルダーに埋め込みコードが表示されます：

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

このスクリプトは、圧縮前で約4 KBの小さなローダーです。data-widgetを読み取り、metalapi-widget-<id>というidを持つ要素を探して、https://metalapi.com/embed/<id>を読み込むiframeをそこに挿入します。コンテナが見つからない場合は、ローダーがscriptタグの直前にコンテナを作成します。フレーム内のウィジェットはpostMessageで自身の高さを通知し、ローダーがそれに合わせてiframeのサイズを変更するため、テーブルが3行から6行に増えてもスクロールバーは表示されません。

scriptタグが複数回記述されていても、ローダーが実行されるのはページごとに1回だけです。1つのページに複数のウィジェットを表示するには、スクリプトを1回だけ読み込み、各コンテナにidの代わりにdata-metalapi-widget属性を付けます：

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

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

ローダーがこれらのコンテナを探すのは、ページの読み込みが完了したときの1回だけです。シングルページアプリでのルート変更後など、クライアントサイドのJavaScriptが後から追加したコンテナは検出されません。その場合や、スクリプトをまったく追加できない場合は、フレームを直接埋め込んでください：

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

ローダーがないとiframeは自身のサイズを変更できないため、選んだレイアウトに合った高さを指定してください。以前のウィジェットジェネレーターで作られた古いnew MetalAPIWidget({...})スニペットを使っているページも、引き続き動作します。保存済みのウィジェットはIDに基づいて描画され、古いスニペットに残っているAPIキーは無視されます。

通常のHTML、WordPress、Shopify

通常のHTML。 サイドバーや価格ページの上部など、ウィジェットを表示したい場所にスニペットを貼り付けます。async属性が付いているため、ローダーのダウンロード中にページのほかの部分の表示がブロックされることはありません。

WordPress。 ブロックエディターでカスタムHTMLブロックを追加し、スニペットを貼り付けます。すべてのページにウィジェットを表示するには、サイドバーやフッターのウィジェットエリアにカスタムHTMLウィジェットとして配置するか、テーマのテンプレートファイルに記述します。マルチサイトのネットワークや制限の厳しいホスティングプランなど、環境によってはコンテンツから<script>タグが削除されることがあります。公開後にウィジェットが表示されない場合は、ページのソースを確認してください。scriptタグが消えている場合は、スクリプトが不要なiframe版を使ってください。

Shopify。 テーマエディター（オンラインストア → テーマ → カスタマイズ）で、ウィジェットを置きたいテンプレートにカスタムLiquidのセクションまたはブロックを追加し、スニペットを貼り付けます。商品ページにだけ表示するには、商品テンプレートにブロックを追加します。テーマのコードを編集する場合は、セクションファイルに直接スニペットを記述することもできます。

その他のサイトビルダー。 HTMLや埋め込み用の要素を持つビルダーであれば、同じ方法で使えます。たとえば、WebflowのCode EmbedやSquarespaceのコードブロックです。ビルダーによってはカスタムHTMLを独自のiframeで囲むため、自動のサイズ調整がそこまで届きません。その場合は、埋め込み要素に固定の高さを指定してください。

プランの上限、鮮度、ブランド表示

保存したウィジェットは、所有者のプランで許可される鮮度の価格を表示し、新しいデータを自動でポーリングします。ポーリング間隔はプランの更新間隔に従いますが、30秒より短くなることも、15分より長くなることもありません：

FreeとLiteでは、ウィジェットは価格の変動よりも頻繁に新しいデータを確認するため、ページを再読み込みしなくても更新が反映されます。どのウィジェットも下部にデータの時刻をUTCで表示するので、訪問者は価格がどれだけ新しいかを確認できます。プランごとの機能一覧は料金ページをご覧ください。

パフォーマンスとレイアウトシフト

ウィジェットがページに与える負荷はごくわずかです：

• ブロッキングしないスクリプト。 ローダーはasyncで読み込まれ、1時間のブラウザキャッシュ付きで配信されるため、再訪問者は通常、ダウンロードし直す必要がありません。
• 遅延読み込みのフレーム。 ローダーはloading="lazy"付きでiframeを作成するため、ページの下のほうにあるウィジェットは、訪問者がその近くまでスクロールしたときに初めて取得されます。
• 分離。 ウィジェットは独自のフレーム内で動作します。サイトのスタイルシートがウィジェットを崩すことはなく、ウィジェットのコードがページに干渉することもありません。
• ページキャッシュも安全。 スニペットは変わらず、価格はフレーム内で読み込まれます。WordPressのキャッシュプラグイン、ShopifyのCDN、その他のフルページキャッシュがHTMLをどれだけ長く保持しても、価格が古いまま固定されることはありません。

唯一考慮が必要なのは、レイアウトシフトです。フレームは高さ120ピクセルで始まり、ウィジェットの実際の高さまで伸びるため、その下のコンテンツが押し下げられることがあります。ビルダーのプレビューで確認した高さを使い、コンテナに最小の高さを指定して、あらかじめスペースを確保してください：

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

ティッカーに必要なスペースは、8種類の金属を並べたテーブルよりはるかに小さいため、サイト全体で共通の値ではなく、ウィジェットごとに値を指定してください。

APIを使うべき場合

ウィジェットは完成されたコンポーネントです。ウィジェットではできないことが必要な場合は、APIを使ってください：

• 自分のHTML内の価格。 iframe内のテキストは別のドキュメントに属するため、検索エンジンがそれをページの一部として扱わない可能性があります。価格をページのコンテンツの一部にしたい場合は、サーバー側で描画してください。
• 独自のデザイン。 ウィジェットが提供するのは、4つのレイアウト、テーマ、アクセントカラーです。それ以上が必要なら、独自のマークアップを書いてください。
• 計算。 重量と純度に基づく商品価格、買取の見積もり、換算はサーバーで行うべきものです。ジュエリー価格計算ツールのチュートリアルで具体例を紹介しています。
• アプリケーション内のデータ。 チャート、過去データ、価格の保存には、APIドキュメントで説明している過去データと期間指定のエンドポイントが必要です。

APIはサーバーから呼び出し、各レスポンスをプランの更新間隔の間キャッシュしてください。WordPressなら、Transientキャッシュを使ったショートコードで、その両方を数行で実現できます：

<?php
// 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); // プランの更新間隔
    }

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

投稿や固定ページで[gold_price currency="EUR" unit="gram"]のように使います。レスポンスのキーは基準通貨にシンボルを続けたものなので、rates.EURXAUは金1グラムのユーロ建て価格です。キャッシュミスのたびに1リクエストを消費するため、10分のTransientでは、表示する通貨と単位の組み合わせごとに月最大約4,500リクエストとなり、Standardプランに収まります。

代わりにブラウザからAPIを呼び出す必要がある場合は、認証ガイドで説明しているとおり、先にキーを自社ドメインに制限してください。ただし、単に価格を表示するだけなら、ウィジェットのほうが簡単です。キーは不要で、管理すべきキャッシュもなく、後でシンボルを変更しても保守の手間はかかりません。