Fonctionnement
Comme Zonos Checkout s'exécute dans une iframe sur une origine différente, il
ne peut pas accéder directement à la fonction gtag de votre page. Le système de relais résout ce
problème avec une poignée de main en deux étapes (étapes 1-2) suivie du transfert d'événements (étape 3) :
- Checkout envoie un ping au parent — Lorsque le checkout se charge dans l'iframe, il envoie un message à la fenêtre parente indiquant qu'il est prêt à relayer les événements.
- Le parent accuse réception — Le script de relais sur votre page reçoit le ping, détecte votre configuration GA4 existante et signale qu'il est prêt à recevoir les événements.
- Les événements sont transférés — Au fur et à mesure que les acheteurs progressent dans le checkout, chaque
événement analytique est envoyé via
postMessageà votre page, où le script de relais le transmet àgtag.
Tous les messages sont validés par rapport aux origines Zonos de confiance (zonos.com et
iglobalstores.com) en HTTPS uniquement.
Prérequis
- Une propriété GA4 avec un ID de mesure (format :
G-XXXXXXXXXX). Vous pouvez en créer une dans Google Analytics. - Une intégration Checkout legacy qui charge Zonos Checkout dans une iframe sur votre page.
Configuration
Étape 1 : Ajouter la balise GA4 à votre page
Si vous n'avez pas encore GA4 installé sur votre site, ajoutez la balise Google
Analytics 4 standard dans le <head> de la page qui héberge l'iframe Checkout.
Remplacez G-XXXXXXXXXX par votre propre ID de mesure.
<!-- Google tag (gtag.js) --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script> <script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX');</script>Note : Si votre site a déjà la balise GA4 installée (par ex. via Google Tag Manager ou un extrait direct), vous pouvez ignorer cette étape. Le script de relais utilisera votre fonction
gtagexistante.
Vous trouverez cet extrait dans votre propriété GA4 sous Admin -> Data Streams -> sélectionnez votre flux -> View tag instructions -> Install manually.
Étape 2 : Transmettre votre ID de mesure à Zonos Checkout
Indiquez à Zonos Checkout quel ID de mesure GA4 utiliser en définissant
window.Zonos.googleAnalyticId dans le customHTML de votre Checkout. Le
Dashboard Zonos expose un éditeur customHTML sous Checkout settings — ajoutez une
balise <script> comme ceci :
<script> window.Zonos.googleAnalyticId = 'G-XXXXXXXXXX';</script>Cette valeur est envoyée au parent lors de la poignée de main du relais. Si votre page parente
n'a pas déjà gtag chargé, le script de relais injectera la balise GA4
de base pour vous en utilisant cet ID.
Étape 3 : Ajouter le script de relais analytique Zonos
Ajoutez la balise script suivante sur la même page, après la balise GA4. Ce script
écoute les événements analytiques de l'iframe Zonos Checkout et les transmet à
votre gtag.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Exemple complet
Voici à quoi ressemble la configuration complète dans le <head> de votre page :
<head> <!-- ... vos balises head existantes ... --> <!-- Google tag (gtag.js) --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" ></script> <script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX'); </script> <!-- Relais analytique Zonos pour iframe checkout --> <script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js" ></script></head>Voilà. Une fois les deux scripts sur votre page, le script de relais termine automatiquement la poignée de main avec l'iframe checkout et transmet tous les événements de l'entonnoir de checkout à votre propriété GA4.
Référence des événements GA4
Zonos Checkout émet les événements suivants via le relais. Tous les événements incluent
un indicateur isTestMode et le checkoutSessionId.
| Événement↕ | Déclencheur↕ | Métadonnées supplémentaires↕ |
|---|---|---|
zonos-checkout-start | Ouverture du checkout | -- |
zonos-checkout-customer-info | L'acheteur saisit ses informations client | -- |
zonos-checkout-shipping-info | L'acheteur sélectionne un mode d'expédition | serviceLevelId |
zonos-checkout-payment-info | L'acheteur saisit les détails de paiement | paymentMethod |
zonos-checkout-payment-fail | Échec de la tentative de paiement | -- |
zonos-checkout-success | Commande finalisée avec succès | transaction_id, currency, value, items |
zonos-checkout-close | L'acheteur ferme le checkout | -- |
purchase | Commande finalisée (événement e-commerce GA4 standard) | transaction_id, currency, value, items |
Métadonnées de l'événement purchase
L'événement purchase suit le schéma de l'
événement e-commerce GA4 purchase
:
| Champ↕ | Description↕ |
|---|---|
transaction_id | ID de commande Zonos ou ID de session checkout |
currency | Code devise à trois lettres (par ex. USD) |
value | Valeur totale de la commande |
items | Tableau d'articles du panier, chacun avec item_id, item_name, price et quantity |
Débogage
Pour activer la journalisation de débogage du script de relais, ajoutez le paramètre de requête zonosDebug=1
à l'URL de votre page :
https://www.yourstore.com/checkout?zonosDebug=1Ouvrez la console développeur de votre navigateur pour voir les journaux détaillés de la poignée de main du relais et des événements transférés. Cela est utile pour vérifier que :
- Le script de relais reçoit le ping de l'iframe checkout.
- GA4 est configuré avec le bon ID de mesure.
- Les événements sont transférés vers
gtag.
Questions fréquentes
Dois-je modifier mon appel API createTempCart ?
Non. Le système de relais fonctionne indépendamment de l'API createTempCart. Vous devez uniquement
ajouter la balise GA4 et le script de relais à votre page.
Que faire si j'utilise déjà footerHTML pour Google Analytics ?
Le paramètre footerHTML dans l'API
createTempCart
injecte des scripts dans l'iframe checkout, ce qui se limite au suivi
d'événements au niveau de la page dans l'origine de l'iframe. L'approche par relais est recommandée
car elle envoie les événements à votre propre propriété GA4 sur votre domaine, vous offrant une
visibilité complète de l'entonnoir dans une seule propriété.
Vous pouvez supprimer en toute sécurité tout script GA4 de footerHTML après avoir configuré le
relais.
Est-ce compatible avec le mode débogage GA4 dans Google Analytics ?
Oui. Vous pouvez utiliser zonosDebug=1 pour activer les journaux du script de relais dans la console développeur de votre navigateur, et utiliser
GA4 DebugView dans Google
Analytics pour vérifier les événements en temps réel.
Les commandes de test sont-elles suivies ?
Tous les événements incluent un champ isTestMode. Lorsque Checkout est en mode test, les événements
sont toujours envoyés à GA4 mais marqués avec isTestMode: true. Vous pouvez les filtrer
dans GA4 à l'aide de dimensions personnalisées si nécessaire.
Google Analytics 4 pour iframe Checkout
Suivez l'entonnoir complet de checkout avec GA4 lorsque vous utilisez une intégration Checkout legacy basée sur iframe.
Les marchands utilisant l'intégration Checkout legacy (iframe hébergée sur
iglobalstores.com) peuvent désormais suivre les événements analytiques GA4 sur l'ensemble de l'entonnoir de checkout. Zonos Checkout relaie automatiquement les événements analytiques depuis l'iframe vers la page parente à l'aide d'un script de relais léger, de sorte que les événements apparaissent dans votre propriété GA4 comme s'ils provenaient de votre propre site.