Start free trialTry free

← Help center

Hydrogen and headless storefronts

Track a Hydrogen or other headless Shopify storefront with the ROASaurus module.

A headless storefront has no Shopify theme, so the ROASaurus theme embed does not run. Instead you load a small ES module from ROASaurus in the browser. It needs no npm package. Checkout stays on Shopify, where the ROASaurus app pixel (installed with the app) tracks checkouts and purchases as before, and orders still arrive through Shopify's order webhooks.

1. Load the module

Your store key is on the store's Setup › Shopify page in ROASaurus. Load the module in the browser only (not during server rendering):

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 follows every 1.x release. Pin one exact version with /headless@1.0.0.js, or always take the latest with /headless.js. Allow https://app.roasaurus.com in your Content Security Policy for scripts and connections (Hydrogen: scriptSrc and connectSrc in createContentSecurityPolicy).

2. Connect Hydrogen analytics

Hydrogen 2026-04 and earlier: render this component inside <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 and later: add ROASaurus as a destination on the analytics bus, once per page load.

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

The module sends page_viewed as PageView, product_viewed as ViewContent, product_added_to_cart as AddToCart (the added quantity) and cart_viewed as a cart view. ROASaurus forwards them to your ad platforms with the same event ids as their browser pixels.

3. Write the cart attributes

The visitor id on the cart links the Shopify order to the ad click. In Hydrogen, update the cart's attributes with roasaurus.cartAttributes() when a product is added (for example a CartForm with CartForm.ACTIONS.AttributesUpdateInput, or cart.updateAttributes() in your cart action). Keep the attributes the cart already has.

Other headless storefronts can let the module write them through the Storefront API with a public 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

It reads the cart's attributes, adds _tl, the click ids and the market, and saves them with cartAttributesUpdate. A cart seen with consent is also linked to the visitor, so the order matches even when the attributes are missing.

Consent

The module follows Shopify's Customer Privacy API (window.Shopify.customerPrivacy), which Hydrogen loads with its consent settings. Until the shopper's marketing choice is known, events wait. When they decline, no visitor id, click id or cart attribute is kept, and events go out without identifiers and are not forwarded to ad platforms. With your own banner, call roasaurus.setConsent(true) or setConsent(false).

Other calls

Still stuck? Email us.