# 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);
})();
```

5. 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>
```

{% hint style="info" %}
*N'oubliez pas de remplacer `abc.votre-sous-domaine.com` par votre domaine de tracking Sirdata.*
{% endhint %}

***

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://server-side.docs.sirdata.net/sirdata-server-side/installation/cms/shopify-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.