Hydrogen ja headless-kauppasivustot

Seuraa Hydrogen-kauppasivustoa tai muuta headless Shopify -kauppasivustoa ROASaurus-moduulilla.

Headless-kauppasivustolla ei ole Shopify-teemaa, joten ROASauruksen teeman app embed ei toimi. Sen sijaan selaimessa ladataan ROASauruksesta pieni ES module. Se ei vaadi npm-pakettia. Kassa pysyy Shopifyssa, jossa ROASauruksen app-pikseli (asentuu sovelluksen mukana) seuraa kassatapahtumia ja ostoja kuten ennenkin, ja tilaukset tulevat edelleen Shopifyn tilaus-webhookien kautta.

1. Lataa moduuli

Kauppa-avaimesi löytyy ROASauruksessa kaupan Setup › Shopify -sivulta. Lataa moduuli vain selaimessa (ei palvelinrenderöinnin aikana):

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 päivittyy jokaisen 1.x-julkaisun mukana. Lukitse tarkka versio osoitteella /headless@1.0.0.js tai käytä aina uusinta osoitteella /headless.js. Salli https://app.roasaurus.com Content Security Policy -käytännössäsi skripteille ja yhteyksille (Hydrogen: scriptSrc ja connectSrc funktiossa createContentSecurityPolicy).

2. Yhdistä Hydrogen-analytiikka

Hydrogen 2026-04 ja aiemmat: renderöi tämä komponentti <Analytics.Provider>-komponentin sisällä.

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 ja uudemmat: lisää ROASaurus kohteeksi analytiikkaväylään, kerran sivun latausta kohden.

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

Moduuli lähettää tapahtumat näin: page_viewed PageView-tapahtumana, product_viewed ViewContent-tapahtumana, product_added_to_cart AddToCart-tapahtumana (lisätyllä määrällä) ja cart_viewed ostoskorin katseluna. ROASaurus välittää ne mainosalustoillesi samoilla tapahtuma-ID:illä kuin niiden selainpikselit.

3. Kirjoita ostoskorin attribuutit

Ostoskorissa oleva kävijätunnus yhdistää Shopify-tilauksen mainosklikkaukseen. Päivitä Hydrogenissa ostoskorin attribuutit roasaurus.cartAttributes()-kutsulla, kun tuote lisätään (esimerkiksi CartForm-lomakkeella, jossa on CartForm.ACTIONS.AttributesUpdateInput, tai cart.updateAttributes()-kutsulla ostoskorin actionissa). Säilytä attribuutit, jotka ostoskorissa jo on.

Muissa headless-kauppasivustoissa moduuli voi kirjoittaa ne Storefront API:n kautta julkisella tokenilla:

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

Se lukee ostoskorin attribuutit, lisää _tl-tunnisteen, klikkaus-ID:t ja markkinan sekä tallentaa ne cartAttributesUpdate-kutsulla. Suostumuksella nähty ostoskori liitetään myös kävijään, joten tilaus yhdistyy, vaikka attribuutit puuttuisivat.

Suostumus

Moduuli noudattaa Shopifyn Customer Privacy API:a (window.Shopify.customerPrivacy), jonka Hydrogen lataa consent-asetuksillaan. Tapahtumat odottavat, kunnes ostajan markkinointivalinta on tiedossa. Jos ostaja kieltäytyy, kävijätunnusta, klikkaus-ID:tä tai ostoskorin attribuuttia ei säilytetä, ja tapahtumat lähetetään ilman tunnisteita eikä niitä välitetä mainosalustoille. Jos käytät omaa banneria, kutsu roasaurus.setConsent(true) tai setConsent(false).

Muut kutsut

roasaurus.track('Lead', {value: 50, currency: 'EUR'}) lähettää minkä tahansa tapahtuman.
roasaurus.identify({email}) liittää rekisteröitymisen käyntiin (suostumuksella).
roasaurus.handle('product_viewed', payload) ottaa vastaan Hydrogen-tyyppisiä payloadeja muista sovelluskehyksistä.

Etkö vieläkään pääse eteenpäin? Lähetä meille sähköpostia.