Começar teste gratuitoExperimentar grátis

← Centro de ajuda

Hydrogen e lojas headless

Faça o tracking de uma loja Hydrogen ou de outra loja Shopify headless com o módulo da ROASaurus.

Uma loja headless não tem tema do Shopify, por isso o theme embed da ROASaurus não é executado. Em vez disso, carrega no navegador um pequeno módulo ES da ROASaurus. Não precisa de nenhum pacote npm. O checkout continua no Shopify, onde o pixel de app da ROASaurus (instalado com a app) faz o tracking dos checkouts e das compras como antes, e as encomendas continuam a chegar pelos webhooks de encomendas do Shopify.

1. Carregue o módulo

A chave da sua loja está na página Setup › Shopify da loja na ROASaurus. Carregue o módulo apenas 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 ligações (Hydrogen: scriptSrc e connectSrc em createContentSecurityPolicy).

2. Ligue 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 a 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. A ROASaurus reencaminha-os para as 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 liga a encomenda do Shopify ao clique no anúncio. No Hydrogen, atualize os atributos do carrinho com roasaurus.cartAttributes() quando é adicionado um produto (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 através da 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, acrescenta _tl, os IDs de clique e o mercado, e guarda-os com cartAttributesUpdate. Um carrinho visto com consentimento fica também associado ao visitante, pelo que a encomenda é associada mesmo quando faltam os atributos.

Consentimento

O módulo segue a Customer Privacy API do Shopify (window.Shopify.customerPrivacy), que o Hydrogen carrega com as respetivas definições de consent. Enquanto não se souber a escolha de marketing do cliente, os eventos ficam em espera. Se o cliente recusar, não é guardado nenhum ID de visitante, ID de clique nem atributo do carrinho, e os eventos são enviados sem identificadores e não são reencaminhados para as plataformas de anúncios. Com o seu próprio banner, chame roasaurus.setConsent(true) ou setConsent(false).

Outras chamadas

Continua com dificuldades? Envie-nos um email.