← Central de ajuda

Hydrogen e lojas headless

Rastreie uma loja Hydrogen ou outra loja Shopify headless com o módulo do ROASaurus.

Uma loja headless não tem tema do Shopify, então o embed do tema do ROASaurus não é executado. Em vez disso, você carrega no navegador um pequeno módulo ES do ROASaurus. Não é preciso nenhum pacote npm. O checkout continua no Shopify, onde o pixel de app do ROASaurus (instalado com o app) rastreia checkouts e compras como antes, e os pedidos continuam chegando pelos webhooks de pedidos do Shopify.

1. Carregue o módulo

A chave da sua loja fica na página Setup › Shopify da loja no ROASaurus. Carregue o módulo somente no navegador (não durante a renderização no servidor):

const {createRoasaurus} = await import('https://app.roasaurus.com/headless@1.js');
const roasaurus = createRoasaurus({
  storeKey: 'YOUR_STORE_KEY',
  market: 'eu',      // optional: the Shopify Market handle of this storefront
  country: 'NL',     // optional: the shopper's country
});

O /headless@1.js acompanha todas as versões 1.x. Fixe uma versão exata com /headless@1.0.0.js ou use sempre a mais recente com /headless.js. Permita https://app.roasaurus.com na sua Content Security Policy para scripts e conexões (Hydrogen: scriptSrc e connectSrc em createContentSecurityPolicy).

2. Conecte o analytics do Hydrogen

Hydrogen 2026-04 e anteriores: renderize este componente dentro de <Analytics.Provider>.

import {useAnalytics} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function RoasaurusAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('ROASaurus');
  useEffect(() => {
    import(/* @vite-ignore */ 'https://app.roasaurus.com/headless@1.js').then(({createRoasaurus}) => {
      const roasaurus = createRoasaurus({storeKey: 'YOUR_STORE_KEY'});
      roasaurus.subscribeHydrogen(subscribe);
      ready();
    });
  }, []);
  return null;
}

Hydrogen 2026-10 e posteriores: adicione o ROASaurus como destino no barramento de analytics, uma vez por carregamento de página.

const roasaurus = createRoasaurus({storeKey: 'YOUR_STORE_KEY'});
roasaurus.addToBus(window.Shopify.analytics);

O módulo envia page_viewed como PageView, product_viewed como ViewContent, product_added_to_cart como AddToCart (a quantidade adicionada) e cart_viewed como visualização do carrinho. O ROASaurus os encaminha para suas plataformas de anúncios com os mesmos IDs de evento dos pixels do navegador dessas plataformas.

3. Grave os atributos do carrinho

O ID do visitante no carrinho vincula o pedido do Shopify ao clique no anúncio. No Hydrogen, atualize os atributos do carrinho com roasaurus.cartAttributes() quando um produto for adicionado (por exemplo, um CartForm com CartForm.ACTIONS.AttributesUpdateInput, ou cart.updateAttributes() na action do carrinho). Mantenha os atributos que o carrinho já tem.

Outras lojas headless podem deixar o módulo gravá-los pela Storefront API com um token público:

const roasaurus = createRoasaurus({
  storeKey: 'YOUR_STORE_KEY',
  shopDomain: 'your-store.myshopify.com',
  storefrontAccessToken: 'PUBLIC_STOREFRONT_TOKEN',
});
await roasaurus.beforeCheckout(cart);   // before you send the shopper to cart.checkoutUrl

O módulo lê os atributos do carrinho, adiciona _tl, os IDs de clique e o mercado, e os salva com cartAttributesUpdate. Um carrinho visto com consentimento também fica vinculado ao visitante, então o pedido é associado mesmo quando os atributos estão ausentes.

Consentimento

O módulo segue a Customer Privacy API do Shopify (window.Shopify.customerPrivacy), que o Hydrogen carrega com as configurações de consent dele. Enquanto a escolha de marketing do cliente não for conhecida, os eventos ficam aguardando. Se o cliente recusar, nenhum ID de visitante, ID de clique ou atributo do carrinho é mantido, e os eventos são enviados sem identificadores e não são encaminhados às plataformas de anúncios. Com o seu próprio banner, chame roasaurus.setConsent(true) ou setConsent(false).

Outras chamadas

• roasaurus.track('Lead', {value: 50, currency: 'EUR'}) envia qualquer evento.
• roasaurus.identify({email}) vincula um cadastro à visita (com consentimento).
• roasaurus.handle('product_viewed', payload) aceita payloads no formato do Hydrogen vindos de outros frameworks.

Ainda com dúvidas? Escreva para nós.