Como adicionar um widget de cotação do ouro ao vivo ao seu site

O que você está incorporando

Um widget da MetalAPI é um pequeno quadro de preços que a MetalAPI hospeda para você. Você o configura uma vez no painel, cola um snippet de duas linhas na sua página, e os visitantes veem os preços atuais de ouro, prata, platina, paládio, metais industriais, energia, moedas ou cripto. O widget é renderizado dentro de um iframe servido a partir de metalapi.com. Não há código de backend para escrever, nenhuma chave de API no seu HTML e nada para atualizar do seu lado quando os preços mudam.

Isso torna o widget a opção mais rápida para sites de conteúdo, joalherias e lojas de metais para investimento, páginas de notícias e blogs que querem mostrar o preço atual ao lado do próprio conteúdo. Se você precisa do preço dentro do seu próprio markup ou em um cálculo, a API REST é mais adequada. A última seção deste artigo trata desse caso.

O tráfego dos widgets é atendido pelo endpoint de widgets da MetalAPI, e não pela sua chave de API, então as visualizações de página não consomem a sua cota mensal de requisições. O seu plano define quantos widgets você pode salvar e quão recentes são os preços deles; os dois pontos são abordados abaixo.

Crie o widget no painel

Os widgets estão incluídos em todos os planos, inclusive no Free. Crie uma conta, abra Widgets no painel e clique em New widget. O editor mostra uma prévia ao vivo ao lado do formulário, para que você experimente as opções antes de salvar:

Dois detalhes passam despercebidos com facilidade. Se você deixar a unidade em onça troy, os metais industriais são exibidos na unidade usual dos seus mercados, então o cobre aparece por libra-peso enquanto o ouro continua por onça troy. Além disso, uma unidade em gramas ou quilogramas converte apenas os metais: moedas, energia e cripto mantêm as suas próprias unidades. Se você não tem certeza de qual unidade de peso os seus visitantes esperam, o guia de conversão de unidades explica as diferenças.

Ao salvar, o widget recebe um ID público como w_abc123. O código de incorporação faz referência apenas a esse ID; a configuração fica nos servidores da MetalAPI. Quando você mudar depois os símbolos, as cores ou o layout, todas as páginas que incorporam o widget mostram a nova versão no próximo carregamento, sem nenhuma alteração no snippet do seu site. A lista de widgets também tem um interruptor Live para tirar um widget do ar sem excluí-lo, além de um contador de visualizações por widget.

O código de incorporação, linha por linha

Depois de salvar, o editor mostra o código de incorporação:

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

O script é um pequeno carregador, com cerca de 4 KB antes da compressão. Ele lê data-widget, procura o elemento com o id metalapi-widget-<id> e o preenche com um iframe que carrega https://metalapi.com/embed/<id>. Se o contêiner não existir, o carregador cria um logo antes da tag script. O widget dentro do frame informa a sua altura com postMessage, e o carregador redimensiona o iframe de acordo, então uma tabela que cresce de três para seis linhas nunca mostra uma barra de rolagem.

O carregador roda apenas uma vez por página, mesmo que a tag script apareça várias vezes. Para mostrar vários widgets em uma página, inclua o script uma única vez e marque cada contêiner com um atributo data-metalapi-widget em vez de um 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>

O carregador procura esses contêineres uma única vez, quando a página termina de carregar. Ele não vê contêineres que o JavaScript do lado do cliente adiciona depois, por exemplo após uma mudança de rota em uma single-page app. Nesse caso, ou quando você não puder adicionar scripts, incorpore o frame diretamente:

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

Sem o carregador, o iframe não consegue se redimensionar, então dê a ele uma altura que caiba no layout escolhido. Páginas que ainda usam o snippet antigo new MetalAPIWidget({...}), do gerador de widgets anterior, continuam funcionando: os widgets salvos são renderizados pelo ID, e qualquer chave de API deixada em um snippet antigo é ignorada.

HTML puro, WordPress e Shopify

HTML puro. Cole o snippet onde o widget deve aparecer, por exemplo em uma barra lateral ou no topo de uma página de preços. Graças ao atributo async, o carregador nunca bloqueia o resto da página enquanto é baixado.

WordPress. No editor de blocos, adicione um bloco HTML personalizado (Custom HTML) e cole o snippet. Para mostrar o widget em todas as páginas, coloque-o em um widget HTML personalizado em uma área de widgets da barra lateral ou do rodapé, ou nos arquivos de template do seu tema. Algumas configurações, como redes multisite ou planos de hospedagem restritos, removem as tags <script> do conteúdo. Se o widget não aparecer depois da publicação, veja o código-fonte da página. Se a tag script estiver faltando, use a versão com iframe, que não precisa de script.

Shopify. No editor de temas (Loja virtual → Temas → Personalizar, ou Online Store → Themes → Customize com o admin em inglês), adicione uma seção ou um bloco Liquid personalizado (Custom Liquid) ao template em que o widget deve ficar e cole o snippet. Para mostrá-lo apenas nas páginas de produto, adicione o bloco ao template de produto. Você também pode colocar o snippet diretamente em um arquivo de seção ao editar o código do tema.

Outros criadores de sites. Criadores com um elemento de HTML ou de incorporação funcionam da mesma forma, por exemplo o code embed do Webflow ou um bloco de código do Squarespace. Alguns criadores envolvem o HTML personalizado em um iframe próprio, e o redimensionamento automático não consegue atravessá-lo. Nesse caso, dê uma altura fixa ao elemento de incorporação.

Limites dos planos, atualização e marca

Um widget salvo mostra preços tão recentes quanto o plano do seu dono permite e busca novos dados sozinho. O intervalo de consulta segue o intervalo de atualização do plano, mas nunca é menor que 30 segundos nem maior que 15 minutos:

No Free e no Lite, o widget verifica se há novos dados com mais frequência do que os preços mudam, então ele capta cada atualização sem recarregar a página. Todo widget mostra no rodapé o horário dos seus dados em UTC, para que os visitantes vejam o quão atuais são os preços. A lista completa de recursos por plano está na página de preços.

Desempenho e mudança de layout

Um widget acrescenta muito pouco a uma página:

• Script não bloqueante. O carregador é carregado com async e servido com cache de navegador de uma hora, então os visitantes recorrentes geralmente não o baixam de novo.
• Frames com lazy loading. O carregador cria o iframe com loading="lazy", então um widget no fim da página só é buscado quando o visitante rola até perto dele.
• Isolamento. O widget roda dentro do seu próprio frame. As suas folhas de estilo não conseguem quebrá-lo, e o código dele não consegue mexer na sua página.
• O cache de página é seguro. O snippet nunca muda, e os preços são carregados dentro do frame. Plugins de cache do WordPress, a CDN da Shopify ou qualquer outro cache de página inteira podem guardar o seu HTML pelo tempo que quiserem sem congelar o preço.

O único ponto a planejar é a mudança de layout. O frame começa com 120 pixels e depois cresce até a altura real do widget, o que pode empurrar para baixo o conteúdo que vem depois dele. Reserve o espaço com antecedência definindo uma altura mínima no contêiner, com a altura que você vê na prévia do editor:

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

Um ticker precisa de muito menos espaço do que uma tabela com oito metais, então use um valor por widget em vez de um padrão para o site inteiro.

Quando usar a API em vez do widget

Um widget é um componente pronto. Use a API quando você precisar de algo que um widget não faz:

• Preços no seu próprio HTML. O texto dentro de um iframe pertence a outro documento, então os mecanismos de busca podem não tratá-lo como parte da sua página. Se o preço deve fazer parte do conteúdo da página, renderize-o no servidor.
• O seu próprio design. Os widgets oferecem quatro layouts, um tema e uma cor de destaque. Para qualquer coisa além disso, escreva o seu próprio markup.
• Cálculos. Preços de produtos baseados em peso e pureza, cotações de recompra e conversões ficam no seu servidor. O tutorial da calculadora de preços de joias mostra um exemplo passo a passo.
• Dados na sua aplicação. Gráficos, histórico e preços armazenados exigem os endpoints historical e timeframe descritos na documentação da API.

Chame a API a partir do seu servidor e mantenha cada resposta em cache pelo intervalo de atualização do seu plano. No WordPress, um shortcode com cache em transient faz as duas coisas em poucas linhas:

<?php
// No 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); // o intervalo de atualização do seu plano
    }

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

Use-o em qualquer post ou página como [gold_price currency="EUR" unit="gram"]. A chave da resposta é a moeda base seguida do símbolo, então rates.EURXAU é o preço de um grama de ouro em euros. Cada cache miss custa uma requisição, então um transient de 10 minutos usa no máximo cerca de 4.500 requisições por mês para cada moeda e unidade exibidas, o que cabe no plano Standard.

Se você precisar chamar a API pelo navegador, restrinja antes a chave aos seus próprios domínios, como descrito no guia de autenticação. Para uma simples exibição de preços, porém, o widget continua sendo a escolha mais simples: sem chave, sem cache para gerenciar e nada para manter quando você mudar os símbolos mais tarde.