Essayer gratuitementEssai gratuit

← Centre d’aide

Hydrogen et vitrines headless

Suivez une vitrine Hydrogen ou une autre vitrine Shopify headless avec le module ROASaurus.

Une vitrine headless n’a pas de thème Shopify : l’intégration au thème de ROASaurus ne s’exécute donc pas. À la place, vous chargez dans le navigateur un petit ES module de ROASaurus. Aucun package npm n’est nécessaire. Le checkout reste sur Shopify, où le pixel d’application ROASaurus (installé avec l’application) suit les checkouts et les achats comme avant, et les commandes arrivent toujours via les webhooks de commande de Shopify.

1. Chargez le module

Votre clé de boutique se trouve sur la page Setup › Shopify de la boutique dans ROASaurus. Chargez le module uniquement dans le navigateur (pas pendant le rendu côté serveur) :

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 suit chaque version 1.x. Fixez une version précise avec /headless@1.0.0.js, ou prenez toujours la plus récente avec /headless.js. Autorisez https://app.roasaurus.com dans votre Content Security Policy pour les scripts et les connexions (Hydrogen : scriptSrc et connectSrc dans createContentSecurityPolicy).

2. Connectez l’analytics de Hydrogen

Hydrogen 2026-04 et versions antérieures : effectuez le rendu de ce composant à l’intérieur de <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 et versions ultérieures : ajoutez ROASaurus comme destination sur le bus d’analytics, une fois par chargement de page.

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

Le module envoie page_viewed comme PageView, product_viewed comme ViewContent, product_added_to_cart comme AddToCart (la quantité ajoutée) et cart_viewed comme une consultation du panier. ROASaurus les transmet à vos plateformes publicitaires avec les mêmes identifiants d’événement que leurs pixels du navigateur.

3. Écrivez les attributs du panier

L’identifiant visiteur sur le panier relie la commande Shopify au clic publicitaire. Dans Hydrogen, mettez à jour les attributs du panier avec roasaurus.cartAttributes() lorsqu’un produit est ajouté (par exemple un CartForm avec CartForm.ACTIONS.AttributesUpdateInput, ou cart.updateAttributes() dans votre action de panier). Conservez les attributs que le panier possède déjà.

Les autres vitrines headless peuvent laisser le module les écrire via la Storefront API avec un jeton 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

Le module lit les attributs du panier, ajoute _tl, les identifiants de clic et le marché, puis les enregistre avec cartAttributesUpdate. Un panier vu avec consentement est aussi relié au visiteur : la commande est donc associée même lorsque les attributs manquent.

Consentement

Le module suit la Customer Privacy API de Shopify (window.Shopify.customerPrivacy), que Hydrogen charge avec ses paramètres consent. Tant que le choix marketing de l’acheteur n’est pas connu, les événements sont mis en attente. S’il refuse, aucun identifiant visiteur, identifiant de clic ni attribut de panier n’est conservé, et les événements partent sans identifiants et ne sont pas transmis aux plateformes publicitaires. Avec votre propre bannière, appelez roasaurus.setConsent(true) ou setConsent(false).

Autres appels

Toujours bloqué ? Écrivez-nous.