Hydrogen și vitrine headless

Urmărește o vitrină Hydrogen sau o altă vitrină Shopify headless cu modulul ROASaurus.

O vitrină headless nu are temă Shopify, așa că încorporarea ROASaurus în temă nu rulează. În schimb, încarci în browser un mic ES module de la ROASaurus. Nu are nevoie de niciun pachet npm. Checkout-ul rămâne pe Shopify, unde pixelul de aplicație ROASaurus (instalat odată cu aplicația) urmărește checkout-urile și achizițiile ca până acum, iar comenzile sosesc în continuare prin webhook-urile de comenzi ale Shopify.

1. Încarcă modulul

Cheia magazinului se află în ROASaurus, pe pagina Setup › Shopify a magazinului. Încarcă modulul doar în browser (nu în timpul randării pe 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 se actualizează cu fiecare versiune 1.x. Fixează o versiune exactă cu /headless@1.0.0.js sau ia mereu cea mai nouă versiune cu /headless.js. Permite https://app.roasaurus.com în Content Security Policy pentru scripturi și conexiuni (Hydrogen: scriptSrc și connectSrc în createContentSecurityPolicy).

2. Conectează analytics-ul din Hydrogen

Hydrogen 2026-04 și versiunile anterioare: randează această componentă în interiorul <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 și versiunile ulterioare: adaugă ROASaurus ca destinație pe bus-ul de analytics, o singură dată la fiecare încărcare a paginii.

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

Modulul trimite page_viewed ca PageView, product_viewed ca ViewContent, product_added_to_cart ca AddToCart (cu cantitatea adăugată) și cart_viewed ca vizualizare a coșului. ROASaurus le transmite platformelor tale de publicitate cu aceleași event id-uri ca pixelii lor din browser.

3. Scrie atributele coșului

Id-ul vizitatorului din coș leagă comanda Shopify de click-ul pe reclamă. În Hydrogen, actualizează atributele coșului cu roasaurus.cartAttributes() când se adaugă un produs (de exemplu un CartForm cu CartForm.ACTIONS.AttributesUpdateInput sau cart.updateAttributes() în action-ul coșului). Păstrează atributele pe care coșul le are deja.

Alte vitrine headless pot lăsa modulul să le scrie prin Storefront API, cu un token public:

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

Citește atributele coșului, adaugă _tl, click id-urile și piața, apoi le salvează cu cartAttributesUpdate. Un coș văzut cu consimțământ este legat și de vizitator, așa că comanda se asociază chiar și când atributele lipsesc.

Consimțământ

Modulul urmează Customer Privacy API din Shopify (window.Shopify.customerPrivacy), pe care Hydrogen îl încarcă cu setările sale consent. Până când alegerea de marketing a cumpărătorului este cunoscută, evenimentele așteaptă. Dacă refuză, nu se păstrează niciun id de vizitator, click id sau atribut de coș, iar evenimentele sunt trimise fără identificatori și nu sunt transmise platformelor de publicitate. Cu propriul banner, apelează roasaurus.setConsent(true) sau setConsent(false).

Alte apeluri

roasaurus.track('Lead', {value: 50, currency: 'EUR'}) trimite orice eveniment.
roasaurus.identify({email}) leagă o înscriere de vizită (cu consimțământ).
roasaurus.handle('product_viewed', payload) preia payload-uri în stil Hydrogen din alte framework-uri.

Tot nu merge? Scrie-ne un email.