Empieza la prueba gratisPrueba gratis

← Centro de ayuda

Hydrogen y tiendas headless

Haz el tracking de una tienda Hydrogen u otra tienda Shopify headless con el módulo de ROASaurus.

Una tienda headless no tiene tema de Shopify, así que la incrustación en el tema de ROASaurus no se ejecuta. En su lugar, cargas en el navegador un pequeño ES module de ROASaurus. No necesita ningún paquete npm. El checkout sigue en Shopify, donde el píxel de app de ROASaurus (instalado con la app) registra los checkouts y las compras como hasta ahora, y los pedidos siguen llegando a través de los webhooks de pedidos de Shopify.

1. Carga el módulo

Tu clave de la tienda está en la página Setup › Shopify de la tienda en ROASaurus. Carga el módulo solo en el navegador (no durante el renderizado en el 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
});

/headless@1.js sigue cada versión 1.x. Fija una versión exacta con /headless@1.0.0.js, o usa siempre la más reciente con /headless.js. Permite https://app.roasaurus.com en tu Content Security Policy para scripts y conexiones (Hydrogen: scriptSrc y connectSrc en createContentSecurityPolicy).

2. Conecta la analítica de Hydrogen

Hydrogen 2026-04 y anteriores: renderiza 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 y posteriores: añade ROASaurus como destino en el bus de analítica, una vez por carga de página.

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

El módulo envía page_viewed como PageView, product_viewed como ViewContent, product_added_to_cart como AddToCart (la cantidad añadida) y cart_viewed como una vista del carrito. ROASaurus los reenvía a tus plataformas publicitarias con los mismos ids de evento que sus píxeles del navegador.

3. Escribe los atributos del carrito

El id de visitante en el carrito vincula el pedido de Shopify con el clic en el anuncio. En Hydrogen, actualiza los atributos del carrito con roasaurus.cartAttributes() cuando se añada un producto (por ejemplo, un CartForm con CartForm.ACTIONS.AttributesUpdateInput, o cart.updateAttributes() en la action de tu carrito). Conserva los atributos que el carrito ya tenga.

Otras tiendas headless pueden dejar que el módulo los escriba a través de la Storefront API con un 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

El módulo lee los atributos del carrito, añade _tl, los click ids y el mercado, y los guarda con cartAttributesUpdate. Un carrito visto con consentimiento también se vincula al visitante, así que el pedido se asocia incluso cuando faltan los atributos.

Consentimiento

El módulo sigue la Customer Privacy API de Shopify (window.Shopify.customerPrivacy), que Hydrogen carga con su configuración de consent. Mientras no se conozca la elección de marketing del comprador, los eventos esperan. Si la rechaza, no se guarda ningún id de visitante, click id ni atributo del carrito, y los eventos se envían sin identificadores y no se reenvían a las plataformas publicitarias. Con tu propio banner, llama a roasaurus.setConsent(true) o setConsent(false).

Otras llamadas

¿Sigues con problemas? Escríbenos.