← Hilfecenter

Hydrogen und Headless-Storefronts

Tracke eine Hydrogen- oder andere Headless-Storefront von Shopify mit dem ROASaurus-Modul.

Eine Headless-Storefront hat kein Shopify-Theme, deshalb läuft die App-Einbettung von ROASaurus im Theme dort nicht. Stattdessen lädst du im Browser ein kleines ES module von ROASaurus. Dafür ist kein npm-Paket nötig. Der Checkout bleibt bei Shopify, wo das App-Pixel von ROASaurus (mit der App installiert) Checkouts und Käufe wie bisher trackt, und Bestellungen kommen weiterhin über die Bestell-Webhooks von Shopify an.

1. Lade das Modul

Deinen Shop-Schlüssel findest du in ROASaurus auf der Seite Setup › Shopify des Shops. Lade das Modul nur im Browser (nicht beim serverseitigen Rendern):

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 folgt jedem 1.x-Release. Mit /headless@1.0.0.js legst du eine exakte Version fest, mit /headless.js bekommst du immer die neueste. Erlaube https://app.roasaurus.com in deiner Content Security Policy für Scripts und Verbindungen (Hydrogen: scriptSrc und connectSrc in createContentSecurityPolicy).

2. Binde Hydrogen-Analytics an

Hydrogen 2026-04 und älter: Rendere diese Komponente innerhalb von <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 und neuer: Füge ROASaurus als Ziel im Analytics-Bus hinzu, einmal pro Seitenladevorgang.

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

Das Modul sendet page_viewed als PageView, product_viewed als ViewContent, product_added_to_cart als AddToCart (die hinzugefügte Menge) und cart_viewed als Warenkorbansicht. ROASaurus leitet sie mit denselben Event-IDs wie deren Browser-Pixel an deine Werbeplattformen weiter.

3. Schreibe die Warenkorb-Attribute

Die Besucher-ID im Warenkorb verknüpft die Shopify-Bestellung mit dem Anzeigenklick. Aktualisiere in Hydrogen die Attribute des Warenkorbs mit roasaurus.cartAttributes(), wenn ein Produkt hinzugefügt wird (zum Beispiel über ein CartForm mit CartForm.ACTIONS.AttributesUpdateInput oder über cart.updateAttributes() in deiner Cart-Action). Behalte die Attribute bei, die der Warenkorb bereits hat.

Andere Headless-Storefronts können die Attribute vom Modul über die Storefront API mit einem öffentlichen Token schreiben lassen:

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

Das Modul liest die Attribute des Warenkorbs, ergänzt _tl, die Click-IDs und den Markt und speichert sie mit cartAttributesUpdate. Ein Warenkorb, der mit Einwilligung erfasst wurde, wird außerdem mit dem Besucher verknüpft, sodass die Bestellung auch dann zugeordnet wird, wenn die Attribute fehlen.

Einwilligung

Das Modul folgt der Customer Privacy API von Shopify (window.Shopify.customerPrivacy), die Hydrogen mit seinen consent-Einstellungen lädt. Solange die Marketing-Entscheidung des Käufers nicht bekannt ist, warten die Events. Lehnt er ab, wird keine Besucher-ID, keine Click-ID und kein Warenkorb-Attribut gespeichert, und die Events werden ohne Kennungen gesendet und nicht an Werbeplattformen weitergeleitet. Mit einem eigenen Banner rufst du roasaurus.setConsent(true) oder setConsent(false) auf.

Weitere Aufrufe

• roasaurus.track('Lead', {value: 50, currency: 'EUR'}) sendet ein beliebiges Event.
• roasaurus.identify({email}) verknüpft eine Anmeldung mit dem Besuch (mit Einwilligung).
• roasaurus.handle('product_viewed', payload) verarbeitet Payloads im Hydrogen-Format aus anderen Frameworks.

Kommst du nicht weiter? Schreib uns eine E-Mail.