Inizia la prova gratuitaProva gratis

← Centro assistenza

Hydrogen e vetrine headless

Traccia una vetrina Hydrogen o un’altra vetrina Shopify headless con il modulo ROASaurus.

Una vetrina headless non ha un tema Shopify, quindi l’embed del tema di ROASaurus non viene eseguito. Al suo posto carichi nel browser un piccolo ES module di ROASaurus. Non serve alcun pacchetto npm. Il checkout resta su Shopify, dove il pixel dell’app di ROASaurus (installato con l’app) traccia checkout e acquisti come prima, e gli ordini continuano ad arrivare tramite i webhook degli ordini di Shopify.

1. Carica il modulo

La chiave del negozio si trova nella pagina Setup › Shopify del negozio in ROASaurus. Carica il modulo solo nel browser (non durante il rendering lato 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 segue ogni release 1.x. Fissa una versione esatta con /headless@1.0.0.js, oppure prendi sempre l’ultima con /headless.js. Consenti https://app.roasaurus.com nella tua Content Security Policy per script e connessioni (Hydrogen: scriptSrc e connectSrc in createContentSecurityPolicy).

2. Collega gli analytics di Hydrogen

Hydrogen 2026-04 e precedenti: esegui il rendering di questo componente all’interno di <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 e successivi: aggiungi ROASaurus come destinazione sul bus degli analytics, una volta per caricamento di pagina.

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

Il modulo invia page_viewed come PageView, product_viewed come ViewContent, product_added_to_cart come AddToCart (la quantità aggiunta) e cart_viewed come visualizzazione del carrello. ROASaurus li inoltra alle tue piattaforme pubblicitarie con gli stessi event id dei loro pixel del browser.

3. Scrivi gli attributi del carrello

Il visitor id sul carrello collega l’ordine Shopify al clic sull’annuncio. In Hydrogen, aggiorna gli attributi del carrello con roasaurus.cartAttributes() quando viene aggiunto un prodotto (per esempio un CartForm con CartForm.ACTIONS.AttributesUpdateInput, oppure cart.updateAttributes() nella action del carrello). Mantieni gli attributi che il carrello ha già.

Le altre vetrine headless possono far scrivere gli attributi al modulo tramite la Storefront API con un token pubblico:

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

Il modulo legge gli attributi del carrello, aggiunge _tl, i click id e il mercato e li salva con cartAttributesUpdate. Un carrello visto con il consenso viene anche collegato al visitatore, così l’ordine viene associato anche quando mancano gli attributi.

Consenso

Il modulo segue la Customer Privacy API di Shopify (window.Shopify.customerPrivacy), che Hydrogen carica con le sue impostazioni di consent. Finché la scelta di marketing dell’acquirente non è nota, gli eventi restano in attesa. Se rifiuta, non viene conservato alcun visitor id, click id o attributo del carrello, e gli eventi partono senza identificatori e non vengono inoltrati alle piattaforme pubblicitarie. Con un tuo banner, chiama roasaurus.setConsent(true) o setConsent(false).

Altre chiamate

Hai ancora problemi? Scrivici.