Shopify - Configuration

Implémentation Server-Side Shopify — Guide d'Installation

Ce guide couvre le déploiement complet de la solution server-side Sirdata sur une boutique Shopify. L'installation repose sur deux composants distincts :

1. Un Pixel personnalisé (Customer Events) : collecte les événements dans le contexte sandbox de Shopify.

2. Un script loader : injecté dans le thème principal, il assure la liaison avec votre serveur de tracking.

Architecture : deux contextes, deux dataLayers

Avant de commencer, il est important de comprendre la séparation technique entre les deux environnements d'exécution. Bien qu'ils coexistent sur la même page, ils opèrent dans des mondes isolés.

Contexte	Variable	Rôle
Iframe sandbox Shopify (Custom Pixel)	window.shopifyEventsDataLayer	Reçoit les événements Shopify natifs (page_viewed, checkout_started, etc.)
Page principale (theme.liquid)	window.shopifyDataLayer	Sert de dataLayer pour le loader Sirdata, en remplacement du dataLayer GTM

Ces deux variables ne partagent pas le même scope. Le script distant chargé depuis l'iframe sandbox (/shopify/custom-pixel) récupère shopifyEventsDataLayer depuis son contexte sandboxé. Le loader (/shopify/loader), lui, s'exécute sur la page principale et lit shopifyDataLayer. La communication entre les deux est gérée côté serveur Sirdata.

---

1. Configuration du Pixel Personnalisé (Customer Events)

Shopify isole les pixels tiers dans un lax sandbox (iframe cross-origin). Ce modèle est moins restrictif qu'un strict sandbox (web worker) : il permet d'accéder au DOM, de créer des éléments <script> dynamiques et d'utiliser des APIs navigateur standard. C'est pourquoi le chargement dynamique d'un script externe fonctionne dans ce contexte.

Étapes de configuration

1. Depuis votre interface Shopify, allez dans Paramètres > Événements client.

2. Cliquez sur Ajouter un pixel personnalisé.

3. Nommez-le (ex. : Sirdata_Server_Side).

4. Dans la section Code, insérez le script suivant :

Avant d'enregistrer : remplacez abc.votre-sous-domaine.com par votre domaine de tracking Sirdata réel.

JavaScript

// --- Configuration Sirdata ---
// loadOnCheckoutOnly : contrôle si le pixel Sirdata se charge sur toutes les pages (false)
// ou uniquement sur les pages de checkout (true).
// Valeur recommandée pour un tracking complet si la brique server-side n'est implémentée QUE dans le custom pixel : false
// Valeur recommandée pour un tracking complet si la brique server-side est AUSSI implémentée sur les pages principales (dans le Thème) : true
window.loadOnCheckoutOnly = true;
// --- Fin configuration ---

// Exposition des APIs Shopify vers le script distant Sirdata.
// Dans le lax sandbox, les variables `analytics`, `init` et `browser` sont des globals
// injectés par Shopify. Le script chargé dynamiquement ci-dessous n'y a pas accès
// directement : on les expose via `window` pour qu'il puisse les consommer.
window.apiAnalytics = analytics;
window.apiInit = init;
window.apiBrowser = browser;

// Initialisation du dataLayer sandbox. Les événements Shopify natifs (page_viewed,
// checkout_started, purchase, etc.) sont empilés ici dès qu'ils se déclenchent.
// Ce dataLayer est lu par le script /shopify/custom-pixel une fois chargé.
window.shopifyEventsDataLayer = window.shopifyEventsDataLayer || [];
analytics.subscribe("all_events", event => {
  window.shopifyEventsDataLayer.push(event);
});

// Chargement dynamique du script Sirdata. document.head.appendChild est utilisé
// à la place de insertBefore car il est plus robuste dans l'environnement sandbox
// (évite les erreurs si la collection de scripts est vide).
(function() {
  var script = document.createElement('script');
  script.src = 'https://abc.votre-sous-domaine.com/shopify/custom-pixel';
  script.async = true;
  document.head.appendChild(script);
})();

1. Cliquez sur Enregistrer, puis sur Connecter le pixel.

---

2. Ajout du Script Loader dans le Thème

Le loader doit être présent sur toutes les pages de la boutique. Il initialise le dataLayer principal et charge le script serveur Sirdata depuis le contexte de la page (hors sandbox).

Si GTM est actuellement installé sur le thème : ce script remplace intégralement le snippet GTM. Supprimez le bloc <script> GTM existant dans theme.liquid avant de coller le code ci-dessous.

Étapes d'intégration

1. Allez dans Boutique en ligne > Thèmes.

2. Sur le thème actif, cliquez sur les trois points (...) > Modifier le code.

3. Ouvrez le fichier theme.liquid.

4. Collez le code suivant dans la balise <head>, aussi haut que possible :

HTML

<script>
  window.shopifyDataLayer = window.shopifyDataLayer || [];
  window.shopifyDataLayer.push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' });
</script>
<script src="https://abc.votre-sous-domaine.com/shopify/loader" async></script>

N'oubliez pas de remplacer abc.votre-sous-domaine.com par votre domaine de tracking Sirdata.

---

3. Vérification de l'Installation

Vérification réseau (recommandée)

Dans Chrome DevTools, ouvrez l'onglet Network et filtrez par votre sous-domaine de tracking (ex. : abc.votre-sous-domaine.com). Naviguez sur la boutique et vérifiez que les requêtes suivantes apparaissent avec le statut 200 OK :

• /shopify/loader

• /shopify/custom-pixel

Vérification du dataLayer sandbox

Le Custom Pixel s'exécute dans une iframe isolée. La variable window.shopifyEventsDataLayer n'est pas accessible depuis le contexte principal de la page — taper cette commande dans la console ne retournera rien.

Pour l'inspecter, deux approches :

Option A — Shopify Pixel Helper

Installez l'extension Chrome Shopify Pixel Helper, qui inspecte les pixels actifs et les événements déclenchés sans manipulation DevTools manuelle.

Option B — Contexte iframe dans Chrome DevTools

1. Ouvrez l'onglet Console.

2. Dans le menu déroulant à gauche du prompt (par défaut : top), sélectionnez le contexte de l'iframe Shopify sandbox (souvent nommé Sandbox... ou lié à l'URL du pixel).

3. Tapez window.shopifyEventsDataLayer pour visualiser les événements collectés.

---

⚠️ Points d'attention avant de mettre en production

DNS et configuration Sirdata

Le sous-domaine de tracking (ex. : abc.votre-sous-domaine.com) doit être configuré dans votre interface Sirdata et pointer sur les serveurs Sirdata via un enregistrement DNS de type CNAME. Vérifiez que la propagation DNS est complète avant de tester.

Conflit GTM

Si le snippet GTM n'est pas supprimé du thème avant d'ajouter le loader, les deux scripts coexisteront et pourront générer des doublons d'événements.

Périmètre du flag loadOnCheckoutOnly

Passer ce flag à true restreint le chargement du pixel Sirdata aux pages de checkout uniquement.

• Utile si vous souhaitez limiter le tracking aux événements de conversion.

• Inconvénient : les événements de navigation (Upper Funnel) et de catalogue ne seront alors pas collectés par ce composant.