Как добавить на сайт виджет с актуальной ценой золота

Что именно вы встраиваете

Виджет MetalAPI — это небольшое табло с ценами, которое MetalAPI размещает у себя. Вы один раз настраиваете его в личном кабинете, вставляете на страницу фрагмент кода из двух строк, и посетители видят текущие цены на золото, серебро, платину, палладий, промышленные металлы, энергоносители, валюты или криптовалюты. Виджет отображается внутри iframe, который загружается с metalapi.com. Не нужно писать серверный код, в вашем HTML нет ключа API, и вам ничего не приходится обновлять, когда меняются цены.

Поэтому виджет — самый быстрый вариант для контентных сайтов, ювелирных магазинов, продавцов слитков, новостных страниц и блогов, которым нужно показывать текущую цену рядом со своим контентом. Если цена нужна внутри вашей собственной разметки или в расчётах, лучше подойдёт REST API. Этому случаю посвящён последний раздел статьи.

Трафик виджетов обслуживает отдельный эндпоинт MetalAPI для виджетов, а не ваш ключ API, поэтому просмотры страниц не расходуют месячную квоту запросов. От тарифа зависит, сколько виджетов можно сохранить и насколько свежи их цены; об этом рассказано ниже.

Создание виджета в личном кабинете

Виджеты входят во все тарифы, включая Free. Создайте аккаунт, откройте раздел Widgets в личном кабинете и нажмите New widget. Рядом с формой конструктор показывает живой предпросмотр, так что настройки можно опробовать до сохранения:

Две детали легко упустить. Если оставить единицей тройскую унцию, промышленные металлы показываются в своей обычной рыночной единице: медь — за фунт, а золото — по-прежнему за тройскую унцию. А единица «грамм» или «килограмм» пересчитывает только металлы: валюты, энергоносители и криптовалюты сохраняют свои единицы. Если вы не уверены, какую единицу массы ожидают ваши посетители, различия объясняет руководство по пересчёту единиц.

При сохранении виджет получает публичный идентификатор вида w_abc123. Код для встраивания ссылается только на этот идентификатор, а конфигурация хранится на серверах MetalAPI. Если позже вы измените символы, цвета или макет, все страницы со встроенным виджетом покажут новую версию при следующей загрузке — без изменения фрагмента кода на сайте. В списке виджетов также есть переключатель Live, позволяющий отключить виджет, не удаляя его, и счётчик просмотров для каждого виджета.

Код для встраивания построчно

После сохранения конструктор показывает код для встраивания:

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

Скрипт — это небольшой загрузчик размером около 4 КБ до сжатия. Он читает data-widget, находит элемент с id metalapi-widget-<id> и помещает в него iframe, который загружает https://metalapi.com/embed/<id>. Если контейнера нет, загрузчик создаёт его непосредственно перед тегом script. Виджет внутри фрейма сообщает свою высоту через postMessage, и загрузчик подгоняет под неё размер iframe, поэтому у таблицы, которая выросла с трёх строк до шести, никогда не появляется полоса прокрутки.

Загрузчик выполняется на странице только один раз, даже если тег script встречается несколько раз. Чтобы показать несколько виджетов на одной странице, подключите скрипт один раз и пометьте каждый контейнер атрибутом data-metalapi-widget вместо 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>

Загрузчик ищет такие контейнеры один раз, после загрузки страницы. Контейнеры, которые клиентский 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({...}) из прежнего генератора виджетов, продолжают работать: сохранённые виджеты отображаются по идентификатору, а ключ API, оставшийся в старом фрагменте, игнорируется.

Обычный HTML, WordPress и Shopify

Обычный HTML. Вставьте фрагмент туда, где должен появиться виджет, например в боковую колонку или в начало страницы с ценами. Благодаря атрибуту async загрузчик не блокирует остальную страницу, пока скачивается.

WordPress. В редакторе блоков добавьте блок Custom HTML и вставьте фрагмент. Чтобы виджет был на каждой странице, поместите его в виджет Custom HTML в области виджетов боковой колонки или подвала либо в файлы шаблонов темы. Некоторые конфигурации, например сети мультисайтов или хостинг с ограничениями, удаляют теги <script> из контента. Если после публикации виджет не появился, посмотрите исходный код страницы. Если тега script там нет, используйте вариант с iframe, которому скрипт не нужен.

Shopify. В редакторе темы (Online Store → Themes → Customize) добавьте раздел или блок Custom Liquid в тот шаблон, где должен находиться виджет, и вставьте фрагмент. Чтобы показывать виджет только на страницах товаров, добавьте блок в шаблон товара. Фрагмент можно также вставить прямо в файл раздела при редактировании кода темы.

Другие конструкторы сайтов. Конструкторы с элементом для HTML или встраивания работают так же, например code embed в Webflow или блок кода в Squarespace. Некоторые конструкторы оборачивают пользовательский HTML в собственный iframe, и автоматическое изменение размера через него не работает. В этом случае задайте элементу встраивания фиксированную высоту.

Ограничения тарифов, свежесть данных и брендинг

Сохранённый виджет показывает цены настолько свежие, насколько позволяет тариф его владельца, и сам запрашивает новые данные. Интервал опроса соответствует интервалу обновления тарифа, но никогда не бывает короче 30 секунд или длиннее 15 минут:

На Free и Lite виджет проверяет наличие новых данных чаще, чем меняются цены, поэтому подхватывает каждое обновление без перезагрузки страницы. Внизу каждого виджета указано время его данных по UTC, чтобы посетители видели, насколько актуальны цены. Полный список возможностей каждого тарифа — на странице тарифов.

Производительность и сдвиг макета

Виджет почти не утяжеляет страницу:

• Неблокирующий скрипт. Загрузчик подключается с async и отдаётся с кешированием в браузере на час, поэтому вернувшиеся посетители обычно не скачивают его повторно.
• Ленивая загрузка фреймов. Загрузчик создаёт iframe с loading="lazy", поэтому виджет в нижней части страницы загружается, только когда посетитель прокручивает страницу до него.
• Изоляция. Виджет работает в собственном фрейме. Ваши стили не могут его сломать, а его код не может повлиять на вашу страницу.
• Кеширование страниц безопасно. Фрагмент кода никогда не меняется, а цены загружаются внутри фрейма. Плагины кеширования WordPress, CDN Shopify или любой другой кеш целых страниц могут хранить ваш 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>

Тикеру нужно гораздо меньше места, чем таблице из восьми металлов, поэтому задавайте значение для каждого виджета отдельно, а не одно на весь сайт.

Когда лучше использовать API

Виджет — это готовый компонент. Используйте API, когда нужно то, чего виджет не умеет:

• Цены в вашем собственном HTML. Текст внутри iframe принадлежит другому документу, поэтому поисковые системы могут не считать его частью вашей страницы. Если цена должна быть частью контента страницы, формируйте её на сервере.
• Собственный дизайн. Виджеты предлагают четыре макета, тему и акцентный цвет. Если нужно что-то сверх этого, пишите собственную разметку.
• Расчёты. Цены товаров на основе веса и пробы, расчёт стоимости выкупа и конвертация должны выполняться на вашем сервере. Один такой пример разобран в туториале о калькуляторе цен на ювелирные изделия.
• Данные в вашем приложении. Для графиков, истории и хранения цен нужны эндпоинты исторических данных и периодов, описанные в документации 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 — цена одного грамма золота в евро. Каждый промах кеша стоит один запрос, поэтому transient на 10 минут расходует не более примерно 4 500 запросов в месяц на каждую отображаемую пару валюты и единицы измерения — это укладывается в тариф Standard.

Если же API приходится вызывать из браузера, сначала ограничьте ключ своими доменами, как описано в руководстве по аутентификации. Но для простого показа цены виджет остаётся более простым вариантом: не нужен ключ, не нужно управлять кешем и ничего не придётся поддерживать, если позже вы поменяете символы.