← Helpcentrum

Hydrogen en headless storefronts

Track een Hydrogen- of andere headless Shopify-storefront met de ROASaurus-module.

Een headless storefront heeft geen Shopify-thema, dus de thema-embed van ROASaurus draait niet. In plaats daarvan laad je in de browser een kleine ES module van ROASaurus. Daarvoor is geen npm-pakket nodig. De checkout blijft op Shopify, waar de app pixel van ROASaurus (geïnstalleerd met de app) checkouts en aankopen net als voorheen trackt, en bestellingen komen nog steeds binnen via de order-webhooks van Shopify.

1. Laad de module

Je webshopsleutel staat in ROASaurus op de pagina Setup › Shopify van de webshop. Laad de module alleen in de browser (niet tijdens het renderen op de server):

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 volgt elke 1.x-release. Zet één exacte versie vast met /headless@1.0.0.js, of neem altijd de nieuwste met /headless.js. Sta https://app.roasaurus.com toe in je Content Security Policy voor scripts en verbindingen (Hydrogen: scriptSrc en connectSrc in createContentSecurityPolicy).

2. Koppel Hydrogen-analytics

Hydrogen 2026-04 en eerder: render deze component binnen <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 en later: voeg ROASaurus toe als bestemming op de analytics-bus, één keer per paginalading.

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

De module verstuurt page_viewed als PageView, product_viewed als ViewContent, product_added_to_cart als AddToCart (de toegevoegde hoeveelheid) en cart_viewed als winkelwagenweergave. ROASaurus stuurt ze door naar je advertentieplatforms met dezelfde event-id's als hun browserpixels.

3. Schrijf de winkelwagenattributen

Het bezoeker-id op de winkelwagen koppelt de Shopify-bestelling aan de advertentieklik. Werk in Hydrogen de attributen van de winkelwagen bij met roasaurus.cartAttributes() wanneer een product wordt toegevoegd (bijvoorbeeld met een CartForm met CartForm.ACTIONS.AttributesUpdateInput, of met cart.updateAttributes() in je cart-action). Behoud de attributen die de winkelwagen al heeft.

Andere headless storefronts kunnen de module ze laten schrijven via de Storefront API met een openbaar token:

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

De module leest de attributen van de winkelwagen, voegt _tl, de click-id's en de markt toe en slaat ze op met cartAttributesUpdate. Een winkelwagen die met toestemming is gezien, wordt ook aan de bezoeker gekoppeld, zodat de bestelling ook gekoppeld wordt als de attributen ontbreken.

Toestemming

De module volgt de Customer Privacy API van Shopify (window.Shopify.customerPrivacy), die Hydrogen laadt met zijn consent-instellingen. Zolang de marketingkeuze van de shopper niet bekend is, wachten events. Weigert de shopper, dan wordt er geen bezoeker-id, click-id of winkelwagenattribuut bewaard, en worden events zonder id's verstuurd en niet doorgestuurd naar advertentieplatforms. Gebruik je een eigen banner, roep dan roasaurus.setConsent(true) of setConsent(false) aan.

Andere aanroepen

• roasaurus.track('Lead', {value: 50, currency: 'EUR'}) verstuurt een willekeurig event.
• roasaurus.identify({email}) koppelt een aanmelding aan het bezoek (met toestemming).
• roasaurus.handle('product_viewed', payload) verwerkt payloads in Hydrogen-stijl uit andere frameworks.

Kom je er niet uit? Mail ons.