Suivi des conversions Lightspeed pour les boutiques en ligne eCom

Le suivi des conversions Lightspeed consiste à signaler chaque commande payée de votre boutique en ligne Lightspeed eCom à des plateformes publicitaires comme Meta et TikTok, afin qu’elles puissent attribuer le crédit aux bonnes publicités et optimiser vos campagnes. La méthode fiable est d’envoyer chaque achat à partir des données de commande de Lightspeed, côté serveur, et d’ajouter un court extrait à la page de remerciement qui relie la commande au clic publicitaire.

Ce guide indique à quel produit Lightspeed il s’applique, comment les commandes parviennent à ROASaurus, ce qui est lu dans chaque commande, comment les achats arrivent chez Meta et TikTok, la configuration, les tests et les limites à connaître.

Quel produit Lightspeed ce guide couvre-t-il ?

Lightspeed vend plus d’un produit e-commerce : vérifiez donc d’abord le vôtre. ROASaurus se connecte à Lightspeed eCom (C-Series), la plateforme de boutique en ligne dont le back-office comporte Settings › Website Settings › Web Extras. Son API tourne sur deux clusters :

Chaque adresse d’API contient aussi un code de langue à deux lettres, par exemple /nl/ ou /en/. ROASaurus le demande sous le nom de langue de la boutique et utilise nl quand vous le laissez vide.

Lightspeed propose aussi eCom (E-Series). Lightspeed décrit le passage à E-Series comme une mise à niveau vers un produit distinct, actuellement proposée à certains marchands nord-américains. Le connecteur Lightspeed de ROASaurus lit les commandes uniquement via l’API C-Series : il ne couvre donc pas les boutiques E-Series.

Pourquoi les achats Lightspeed disparaissent-ils dans Meta et TikTok ?

Un pixel dans le navigateur ne signale un achat que si le navigateur de l’acheteur charge la page de remerciement et que le script du pixel s’exécute. Cela échoue dans plusieurs situations courantes :

• Un acheteur paie par redirection, par exemple avec iDEAL ou PayPal, et ferme l’onglet avant que la page de remerciement ne se charge.
• Un bloqueur de publicités ou un réglage de confidentialité du navigateur bloque le script du pixel.
• Le visiteur refuse les cookies marketing : le pixel ne doit donc pas se charger.
• La commande est payée plus tard, par exemple par virement bancaire, sans aucun navigateur impliqué.
• Safari limite la durée de vie des cookies posés par des scripts, si bien que le navigateur peut oublier un ancien clic publicitaire.

Comment les commandes Lightspeed parviennent-elles à ROASaurus ?

Quand vous appuyez sur Create webhook, ROASaurus enregistre dans Lightspeed un webhook pour le groupe orders et l’action updated, au format JSON. À partir de là, Lightspeed appelle ROASaurus chaque fois qu’une commande change.

Pourquoi ROASaurus relit la commande

Lightspeed ajoute un en-tête x-signature à un webhook uniquement quand une application l’a créé. Un webhook créé avec une simple clé API, comme ici, n’est pas signé. L’adresse du webhook contient donc un jeton propre à votre boutique, et ROASaurus ne fait pas confiance au contenu reçu. Il lit lui-même la commande et ses produits depuis l’API Lightspeed et vérifie le statut de paiement.

La vérification toutes les 5 minutes

Toutes les 5 minutes, ROASaurus demande aussi à Lightspeed les commandes mises à jour depuis sa dernière vérification, avec 30 minutes de chevauchement, et enregistre les commandes payées qu’il n’a pas encore. Comme cette vérification s’appuie sur l’heure de mise à jour, une commande payée plusieurs jours après avoir été passée est prise en compte même si l’envoi de son webhook a échoué. Les commandes que ROASaurus a déjà sont ignorées : le webhook et la vérification ne créent donc jamais deux achats.

Côté Lightspeed, un webhook doit recevoir une réponse 2xx en 5 secondes. Les envois échoués sont retentés, jusqu’à 10 tentatives au total, et un webhook dont le taux d’erreur reste au-dessus de 50% pendant 50 heures est désactivé. La vérification toutes les 5 minutes continue de faire arriver les commandes pendant une telle interruption.

Que lit ROASaurus dans une commande Lightspeed ?

La valeur d’achat inclut la TVA

Le priceIncl de Lightspeed est le prix de la commande taxes comprises, et c’est la valeur que ROASaurus envoie. Vos plateformes publicitaires déclarent donc un chiffre d’affaires TVA incluse. Voici l’effet avec 21% de TVA :

Un ROAS d’équilibre s’appuie sur le chiffre d’affaires hors TVA. Divisez le ROAS de la plateforme par 1 plus votre taux de TVA avant de comparer les deux.

Comment une commande Lightspeed est-elle reliée au clic publicitaire ?

Pour attribuer une publicité, la plateforme a besoin des identifiants de clic du visiteur qui a commandé : l’identifiant de clic Meta et l’identifiant de navigateur (fbc, fbp), l’identifiant de clic TikTok (ttclid) et le cookie TikTok (ttp). Le script ROASaurus les enregistre pour chaque visiteur quand il arrive depuis une publicité. ROASaurus n’obtient pas cet identifiant de visiteur à partir de la commande Lightspeed : il relie donc chaque commande à un visiteur d’une autre manière. Il essaie trois méthodes, dans cet ordre :

L’extrait transmet aussi le total de la commande, la devise et l’e-mail du client. ROASaurus enregistre une version hachée de cet e-mail sur le visiteur, ce qui aide à rapprocher la commande suivante du même acheteur. ROASaurus attend brièvement avant d’envoyer chaque achat, afin que l’événement de la page de remerciement puisse arriver en premier, et il retente la correspondance au moment de l’envoi.

Lightspeed variables used by the ROASaurus snippet (Tracking box)

order.information.number      order id and event id order-<number>
order.information.price_incl  value
order.information.currency    currency
order.customer.email          email, hashed on the visitor

La page Orders montre comment chaque commande a été reliée, dans la colonne Matched by : thank_you, email, ip ou not matched. Une commande non rapprochée part quand même vers vos plateformes publicitaires avec ses données de commande, mais sans identifiants de clic, et l’attribution ROASaurus la montre comme directe ou inconnue.

Envoyer les achats Lightspeed à Meta et TikTok

Chaque commande payée devient un événement serveur par plateforme connectée : un Purchase pour la Conversions API de Meta et un CompletePayment pour l’Events API de TikTok, tous deux avec l’identifiant d’événement order-ORD01042. TikTok affiche désormais CompletePayment comme Purchase dans ses rapports. Quand vous cochez l’option de charger aussi le pixel navigateur, l’extrait de la page de remerciement déclenche les mêmes événements dans le navigateur avec le même identifiant d’événement. Meta et TikTok n’en gardent alors qu’un seul exemplaire.

Les mêmes commandes partent vers Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn et les autres plateformes publicitaires lorsque vous les connectez. Les conversions d’achat Google Ads ne sont envoyées que depuis le checkout Shopify : ROASaurus ne les envoie donc pas depuis Lightspeed. Pour la partie Meta de la configuration, consultez le guide de la Meta Conversions API.

Comment configurer le suivi des conversions Lightspeed

1. Ajoutez la boutique dans ROASaurus

   Allez dans Add a store, choisissez Lightspeed eCom et saisissez l’adresse de votre boutique. L’onglet Connection affiche ensuite votre balise de script et l’extrait de la page de remerciement.

2. Ajoutez le script à chaque page

   Dans le back-office Lightspeed, allez dans Settings › Website Settings › Web Extras › Custom JavaScript et collez la balise de script. Lightspeed exécute ce code sur toutes les pages.

3. Ajoutez l’extrait de la page de remerciement

   Sur la même page, dans la zone Tracking, activez Status et collez l’extrait. Lightspeed l’exécute sur la page Thank You après une commande.

4. Créez une clé API

   Allez dans Settings › Store Settings › Developers › New API key. Activez la clé, cochez l’accès en lecture aux commandes, enregistrez, puis sélectionnez Show pour voir le secret.

5. Connectez l’API

   Dans l’onglet Connection, saisissez la clé, le secret, la région et la langue de la boutique. Enregistrez, appuyez sur Test connection, puis sur Create webhook.

6. Connectez vos plateformes publicitaires

   Sur Tracking & platforms, utilisez Connect with Facebook ou Add pixel pour Meta, et Add pixel pour TikTok avec le code du pixel et un jeton d’accès Events API. Cochez l’option de charger aussi le pixel navigateur.

API key          (Settings › Store Settings › Developers)
API secret       (select Show next to the key)
Region           eu  →  api.webshopapp.com
                 us  →  api.shoplightspeed.com
Shop language    nl, en, de ...  (the code in your API addresses)

Consentement

En dehors de Shopify, le script ROASaurus lit le choix du visiteur dans les outils de consentement courants : Cookiebot, OneTrust, les bandeaux IAB TCF et Google consent mode. Avec un autre bandeau de cookies, appelez tlq('consent', true) quand le visiteur accepte les cookies marketing et tlq('consent', false) quand il les refuse. Tant que le visiteur n’a pas accepté, il n’a ni identifiant visiteur ni identifiants de clic, et aucun pixel navigateur ne se déclenche. La commande payée est tout de même envoyée depuis le serveur, avec les données client hachées issues de la commande ainsi que l’adresse IP et le navigateur de la commande. La page d’aide sur le consentement explique les détails.

Comment tester le suivi des conversions Lightspeed ?

• Ouvrez votre boutique avec ?roasaurus=connected dans l’adresse. Une alerte confirme que le script s’exécute. ?roasaurus=debug consigne dans la console du navigateur ce qu’il envoie.
• Dans l’Event log, sous Collected events, les vues de page doivent afficher un identifiant visiteur.
• Passez une commande et assurez-vous que son statut de paiement est paid. Sous Collected events, l’Event log doit alors afficher un Purchase avec votre numéro de commande dans ses données. S’il manque, vérifiez que Status est activé dans la zone Tracking.
• Dans l’onglet Connection, Last order received affiche la commande et Last sync affiche la dernière vérification de 5 minutes, avec l’éventuelle erreur renvoyée par Lightspeed.
• Sous Server deliveries dans l’Event log, chaque plateforme connectée reçoit une ligne avec le statut sent et la réponse de la plateforme.

Pour voir l’événement dans Meta, collez le code d’Events Manager › Test events dans le champ Test event code de votre pixel Meta dans ROASaurus, puis retirez-le quand vous avez terminé. Les réglages du pixel TikTok dans ROASaurus ont le même champ.

Limites et cas particuliers

• C-Series uniquement. Les boutiques Lightspeed eCom E-Series ne peuvent pas utiliser ce connecteur.
• Commandes payées uniquement. Une commande partiellement payée est envoyée quand son statut de paiement passe à paid.
• Paiements tardifs et limite de 7 jours de Meta. Meta accepte les événements serveur jusqu’à 7 jours après l’heure de l’événement. ROASaurus utilise l’heure de création de la commande : une commande payée plus de 7 jours après avoir été passée est donc rejetée par Meta.
• Achats navigateur avant le paiement. L’extrait de la page de remerciement s’exécute quand la commande est passée : les pixels navigateur déclarent donc une commande par virement bancaire avant qu’elle soit payée. Si le paiement arrive plus de 48 heures plus tard, Meta et TikTok ne peuvent pas fusionner les copies navigateur et serveur.
• Les annulations et les remboursements ne sont pas envoyés. Une fois un achat envoyé, il reste dans la plateforme publicitaire.
• Seulement les vues de page, sans code. Les vues de produit et les ajouts au panier ne sont détectés automatiquement que sur Shopify. Sur Lightspeed, un développeur peut les envoyer avec un appel de suivi tlq.
• Limites de l’API. Lightspeed autorise 300 requêtes par 5 minutes, 3,000 par heure et 12,000 par jour et par clé API. Si un autre outil utilise la même clé, ils se partagent ces limites. Lightspeed demande de le contacter pour obtenir une seconde clé.

La page d’intégration Lightspeed rassemble les informations de connexion au même endroit, et la page d’aide pour les autres boutiques en ligne compare Lightspeed aux autres plateformes auxquelles ROASaurus se connecte.

Sources

1. Lightspeed eCom (C-Series) Help Center: Adding a web tracking code
2. Lightspeed eCom (C-Series) Help Center: Creating API keys
3. Lightspeed eCom developers: Webhooks
4. Lightspeed eCom developers: Order
5. Lightspeed eCom developers: Rate limiting

Dans ROASaurus

• Intégration Lightspeed
• Aide : Wix, Lightspeed et autres boutiques en ligne
• Suivi côté serveur
• Intégration Meta

À lire aussi