← Súgóközpont

Hydrogen és headless webáruházak

Kövesd nyomon a Hydrogen- vagy más headless Shopify-webáruházadat a ROASaurus modullal.

A headless webáruháznak nincs Shopify-sablonja, ezért a ROASaurus sablon-beágyazása nem fut le. Helyette egy kis ES module-t töltesz be a ROASaurusból a böngészőben. Ehhez nem kell npm-csomag. A pénztár a Shopifyon marad, ahol a ROASaurus app pixele (amely az alkalmazással együtt települ) ugyanúgy követi a pénztárba lépéseket és a vásárlásokat, mint eddig, a rendelések pedig továbbra is a Shopify rendelés-webhookjain keresztül érkeznek.

1. Töltsd be a modult

A webáruház-kulcsodat a ROASaurusban, a webáruház Setup › Shopify oldalán találod. A modult csak a böngészőben töltsd be (szerveroldali renderelés közben ne):

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
});

A /headless@1.js minden 1.x kiadást követ. Egy pontos verziót a /headless@1.0.0.js címmel rögzíthetsz, vagy a /headless.js címmel mindig a legújabbat töltheted be. Engedélyezd a https://app.roasaurus.com címet a Content Security Policyban a scriptek és a kapcsolatok számára (Hydrogen: scriptSrc és connectSrc a createContentSecurityPolicy hívásban).

2. Csatlakoztasd a Hydrogen analitikát

Hydrogen 2026-04 és korábbi verziók: ezt a komponenst a <Analytics.Provider> elemen belül rendereld.

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 és újabb verziók: add hozzá a ROASaurust célként (destination) az analitikai buszhoz, oldalbetöltésenként egyszer.

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

A modul a page_viewed eseményt PageView-ként, a product_viewed eseményt ViewContent-ként, a product_added_to_cart eseményt AddToCart-ként (a hozzáadott mennyiséggel), a cart_viewed eseményt pedig kosármegtekintésként küldi el. A ROASaurus továbbítja őket a hirdetési platformjaidnak, ugyanazokkal az eseményazonosítókkal, amelyeket a platformok böngészőpixelei használnak.

3. Állítsd be a kosárattribútumokat

A kosáron lévő látogatóazonosító kapcsolja össze a Shopify-rendelést a hirdetési kattintással. Hydrogenben frissítsd a kosár attribútumait a roasaurus.cartAttributes() segítségével, amikor egy termék a kosárba kerül (például egy CartForm komponenssel és a CartForm.ACTIONS.AttributesUpdateInput actionnel, vagy a kosár-actionödben a cart.updateAttributes() hívással). A kosár meglévő attribútumait tartsd meg.

Más headless webáruházakban a modulra is bízhatod, hogy a Storefront API-n keresztül, nyilvános tokennel beírja őket:

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

A modul beolvassa a kosár attribútumait, hozzáadja a _tl értéket, a kattintásazonosítókat és a piacot, majd a cartAttributesUpdate segítségével elmenti őket. A hozzájárulással rögzített kosarat a látogatóhoz is hozzákapcsolja, így a rendelés akkor is párosítható, ha az attribútumok hiányoznak.

Hozzájárulás

A modul a Shopify Customer Privacy API-ját (window.Shopify.customerPrivacy) követi, amelyet a Hydrogen a saját consent beállításaival tölt be. Amíg nem ismert a vásárló marketingdöntése, az események várakoznak. Ha elutasítja, nem tárolódik sem látogatóazonosító, sem kattintásazonosító, sem kosárattribútum, az események azonosítók nélkül mennek el, és a ROASaurus nem továbbítja őket a hirdetési platformoknak. Saját banner esetén hívd meg a roasaurus.setConsent(true) vagy a setConsent(false) függvényt.

További hívások

• roasaurus.track('Lead', {value: 50, currency: 'EUR'}) bármilyen eseményt elküld.
• roasaurus.identify({email}) összekapcsol egy regisztrációt a látogatással (hozzájárulással).
• roasaurus.handle('product_viewed', payload) Hydrogen-stílusú payloadokat fogad más keretrendszerekből.

Elakadtál? Írj nekünk e-mailt.