Testuj za darmoWypróbuj za darmo

← Centrum pomocy

Hydrogen i witryny headless

Śledź witrynę Hydrogen lub inną witrynę headless Shopify za pomocą modułu ROASaurus.

Witryna headless nie ma motywu Shopify, więc osadzenie ROASaurus w motywie nie działa. Zamiast tego ładujesz w przeglądarce niewielki ES module z ROASaurus. Nie wymaga on pakietu npm. Checkout zostaje w Shopify, gdzie piksel aplikacji ROASaurus (instalowany razem z aplikacją) śledzi checkouty i zakupy tak jak dotąd, a zamówienia nadal docierają przez webhooki zamówień Shopify.

1. Załaduj moduł

Klucz sklepu znajdziesz w ROASaurus na stronie Setup › Shopify tego sklepu. Ładuj moduł tylko w przeglądarce (nie podczas renderowania po stronie serwera):

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 aktualizuje się z każdym wydaniem 1.x. Przypnij jedną konkretną wersję przez /headless@1.0.0.js albo zawsze pobieraj najnowszą przez /headless.js. Zezwól na https://app.roasaurus.com w Content Security Policy dla skryptów i połączeń (Hydrogen: scriptSrc i connectSrc w createContentSecurityPolicy).

2. Podłącz analitykę Hydrogen

Hydrogen 2026-04 i starsze: wyrenderuj ten komponent wewnątrz <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 nowsze: dodaj ROASaurus jako miejsce docelowe w szynie analityki, raz na każde załadowanie strony.

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

Moduł wysyła page_viewed jako PageView, product_viewed jako ViewContent, product_added_to_cart jako AddToCart (z dodaną ilością) i cart_viewed jako wyświetlenie koszyka. ROASaurus przekazuje je do twoich platform reklamowych z tymi samymi event id co ich piksele w przeglądarce.

3. Zapisz atrybuty koszyka

Visitor id w koszyku łączy zamówienie Shopify z kliknięciem w reklamę. W Hydrogen aktualizuj atrybuty koszyka za pomocą roasaurus.cartAttributes() po dodaniu produktu (na przykład CartForm z CartForm.ACTIONS.AttributesUpdateInput albo cart.updateAttributes() w akcji koszyka). Zachowaj atrybuty, które koszyk już ma.

W innych witrynach headless moduł może sam je zapisywać przez Storefront API z publicznym tokenem:

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

Odczytuje atrybuty koszyka, dodaje _tl, click id i rynek, a następnie zapisuje je za pomocą cartAttributesUpdate. Koszyk zarejestrowany za zgodą jest też powiązany z odwiedzającym, więc zamówienie zostanie dopasowane nawet wtedy, gdy atrybutów brakuje.

Zgoda

Moduł korzysta z Customer Privacy API Shopify (window.Shopify.customerPrivacy), które Hydrogen ładuje ze swoimi ustawieniami consent. Dopóki nie wiadomo, jaki wybór dotyczący marketingu podjął kupujący, zdarzenia czekają. Gdy odmówi, nie jest zachowywany żaden visitor id, click id ani atrybut koszyka, a zdarzenia są wysyłane bez identyfikatorów i nie trafiają do platform reklamowych. Przy własnym banerze wywołaj roasaurus.setConsent(true) lub setConsent(false).

Inne wywołania

Wciąż coś nie działa? Napisz do nas.