TikTok Events API pour Shopify : configuration et déduplication

La TikTok Events API est la connexion serveur à serveur de TikTok pour les données de conversion. Au lieu de ne s’appuyer que sur le pixel TikTok dans le navigateur de l’acheteur, votre boutique, ou un outil comme ROASaurus, envoie des événements tels que les achats directement à TikTok. TikTok recommande de faire fonctionner l’Events API à côté du pixel et de dédupliquer les deux avec un event_id partagé.

Ce guide couvre ce que l’Events API envoie depuis une boutique Shopify, les noms d’événements Purchase et CompletePayment, l’identifiant de clic et le cookie sur lesquels TikTok s’appuie pour l’association, le fonctionnement de la déduplication, la façon de tester dans TikTok Events Manager, et comment tout configurer dans ROASaurus.

Qu’est-ce que la TikTok Events API ?

Le pixel TikTok est un script sur votre boutique. Il déclenche des événements depuis le navigateur de l’acheteur : il ne compte donc que ce qui se passe pendant que le script se charge et s’exécute. Un bloqueur de publicité, une erreur de script ou un acheteur qui ferme l’onglet avant le chargement de la confirmation de commande peuvent tous l’arrêter.

L’Events API envoie le même type d’événement depuis un serveur. Sur Shopify, la trace la plus fiable d’un achat est la commande elle-même. Shopify signale chaque commande payée par webhook, que le script du navigateur se soit exécuté ou non. C’est l’idée du suivi côté serveur sur Shopify.

Les deux ne sont pas des alternatives. Le conseil de TikTok est de partager les événements par les deux voies, de les garder cohérents tout au long du parcours d’achat, et de laisser TikTok supprimer les doublons.

Quels événements ROASaurus envoie-t-il à TikTok ?

Quatre moments d’une boutique Shopify comptent pour l’optimisation de TikTok : une consultation de produit, un ajout au panier, le début du checkout et l’achat. ROASaurus envoie les quatre à l’Events API et déclenche les mêmes quatre via le pixel TikTok, avec les mêmes identifiants d’événement. Les vues de pages passent uniquement par le pixel.

Dans les réglages du pixel, vous pouvez décocher les événements serveur que vous ne voulez pas envoyer, et ajouter des filtres comme un pays ou une valeur de commande minimale.

Purchase ou CompletePayment ?

TikTok a renommé son événement d’achat. Le nom actuel est Purchase. L’ancien nom, CompletePayment, fonctionne toujours : TikTok convertit les anciens noms de son côté, les affiche sous le nouveau nom dans les rapports, les audiences et l’optimisation, et indique que CompletePayment sera pris en charge indéfiniment. TikTok demande aux nouvelles configurations de pixel d’utiliser Purchase.

ROASaurus envoie CompletePayment, dans le pixel et dans l’Events API. Dans TikTok Events Manager et Ads Manager, ces événements apparaissent sous le nom Purchase. Pour la déduplication, ce qui compte, c’est que les deux copies d’un achat utilisent le même nom d’événement, et c’est le cas.

Comment TikTok associe-t-il un événement à un acheteur ?

Un événement n’aide vos campagnes que si TikTok peut le relier à la personne qui a vu ou cliqué sur la publicité. TikTok appelle ces identifiants des clés de correspondance (match keys), et son guide de l’Events API demande de transmettre toutes les clés de correspondance pertinentes pour augmenter les taux de correspondance. Events Manager présente le résultat sous la forme d’un score Event Match Quality, une moyenne pondérée de la fréquence de présence de chaque clé de correspondance.

TikTok note que le pixel partage par défaut l’adresse IP et le user agent, mais que l’Events API demande de les ajouter à la main. ROASaurus les prend dans la session de checkout de l’acheteur, ou dans la commande s’il n’y avait pas de session. Deux autres clés demandent de l’attention sur Shopify.

ttclid : l’identifiant de clic TikTok

Quand un acheteur clique sur une publicité TikTok, TikTok ajoute ttclid à l’URL de la page d’arrivée. Si votre boutique ne l’enregistre pas sur cette première page, il a disparu au moment où la commande arrive, plusieurs pages plus tard. ROASaurus lit ttclid sur la page d’arrivée, le stocke avec l’identifiant visiteur, l’écrit dans le panier Shopify et l’ajoute à l’événement serveur quand la commande arrive.

_ttp : le cookie du pixel

Le cookie _ttp est un cookie first-party que le pixel TikTok utilise sur votre domaine. ROASaurus le lit sur la boutique et dans le checkout et l’envoie comme ttp dans l’événement serveur. C’est une raison de plus de garder le pixel actif à côté de l’Events API.

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "user": {
      "email": "a3f1…9c2e",
      "phone": "7b40…11d8",
      "external_id": "e05c…4a7f",
      "ttclid": "E.C.P.v3…",
      "ttp": "2Xb7…",
      "ip": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; …)"
    },
    "page": { "url": "https://example-store.com/checkouts/…/thank-you" },
    "properties": {
      "currency": "USD",
      "value": 84,
      "content_type": "product",
      "contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
      "order_id": "5512345678901"
    }
  }]
}

Comment fonctionne la déduplication ?

Quand le pixel et l’Events API signalent le même achat, TikTok reçoit deux événements pour une commande. Pour n’en garder qu’un, TikTok a besoin que deux valeurs soient identiques dans les deux copies : le nom de l’événement et l’event_id. TikTok enregistre alors la première copie reçue pour la mesure et le reporting, et la commande compte donc une seule fois. Cela fonctionne pour les copies correspondantes qui arrivent dans une fenêtre de 48 heures après la première.

ROASaurus construit l’identifiant d’événement d’un achat à partir de l’identifiant de commande Shopify. L’achat de la commande 5512345678901 a l’identifiant d’événement order-5512345678901, dans le pixel de checkout et sur le serveur. Les événements de la boutique, comme les consultations de produits et les ajouts au panier, reçoivent un identifiant aléatoire au moment où ils se produisent, que la copie navigateur et la copie serveur partagent.

Voici ce que cela signifie pour les chiffres. Prenons une boutique d’exemple avec 200 commandes en une semaine. Le pixel se déclenche pour 150 d’entre elles. Les 50 autres acheteurs ont utilisé un bloqueur de publicité, refusé les cookies marketing ou quitté la page avant le chargement de la confirmation. L’Events API envoie les 200.

Le chiffre de 350 est celui qui doit inquiéter. Il rendrait le nombre d’achats de TikTok, et le ROAS qui en découle, supérieurs de 75% à la réalité, car 350 ÷ 200 = 1.75. TikTok utilise aussi ces événements pour l’optimisation et le ciblage : ses enchères apprendraient donc de 150 achats qui n’ont pas eu lieu.

Pourquoi les achats sont-ils comptés deux fois sur Shopify ?

Le double comptage survient quand TikTok reçoit deux copies d’un achat qu’il ne peut pas associer. Vérifiez ces causes avant de vous fier à un bond des achats TikTok :

• Deux outils envoient le même pixel. L’application de canal de vente TikTok sur Shopify peut aussi envoyer des événements pour votre pixel. Ses identifiants d’événement ne correspondent pas à ceux qu’utilise ROASaurus : TikTok compte donc chaque commande deux fois. Déconnectez le pixel dans cette application.
• Le pixel est aussi dans le code de votre thème. Un extrait de pixel collé dans le thème déclenche ses propres événements sans vos identifiants d’événement. Retirez-le et laissez un seul outil charger le pixel.
• Un côté n’a pas d’event_id. Un achat serveur sans event_id, ou avec un nouvel identifiant aléatoire, ne peut pas être associé à la copie du pixel.
• Les noms d’événements diffèrent. TikTok ne déduplique que les événements identiques. Les deux copies d’un achat doivent utiliser le même nom d’événement.

L’article d’aide sur le double comptage passe en revue les mêmes vérifications pour Meta et les autres plateformes.

Comment tester l’Events API dans TikTok Events Manager ?

TikTok Events Manager propose un onglet Test events pour les événements du navigateur et du serveur. Utilisez-le avant de vous fier aux données :

1. Copiez un code d’événement de test

   Dans TikTok Events Manager, ouvrez votre pixel et allez dans Test events. Copiez le code d’événement de test.

2. Collez-le dans ROASaurus

   Ouvrez Tracking & platforms, modifiez le pixel TikTok et collez le code dans le champ Test event code. Les événements serveur le portent désormais.

3. Passez une commande de test

   Visitez votre boutique, consultez un produit, ajoutez-le au panier et finalisez une commande.

4. Vérifiez les deux côtés

   Dans Test events, filtrez sur les événements du navigateur et du serveur. Vous devriez voir l’achat des deux côtés. Dans ROASaurus, l’Event log affiche chaque envoi serveur comme envoyé ou échoué.

5. Retirez le code de test

   Supprimez le code d’événement de test quand vous avez terminé, pour que vos événements serveur réels ne soient plus envoyés comme événements de test.

TikTok peut répondre à une requête par HTTP 200 et rejeter quand même l’événement, avec un code d’erreur dans le corps de la réponse. ROASaurus lit ce code : un événement rejeté apparaît donc comme échoué dans l’Event log au lieu de passer inaperçu.

Après une journée de trafic réel, ouvrez la vue d’ensemble du pixel dans Events Manager. Elle liste chaque événement avec sa méthode de connexion, son score Event Match Quality et la date de sa dernière réception. Les détails de l’événement incluent des informations de correspondance et de déduplication, et Diagnostics liste les problèmes de qualité avec des conseils pour les corriger.

Comment configurer la TikTok Events API sur Shopify avec ROASaurus

Il vous faut une boutique Shopify avec l’application ROASaurus et un accès à TikTok Events Manager. La page de l’intégration TikTok liste chaque champ envoyé par ROASaurus.

1. Connectez votre boutique Shopify

   Allez dans Add a store › Shopify, cliquez sur Install app et activez l’app embed ROASaurus dans l’éditeur de thème. L’embed capture ttclid et le cookie _ttp sur chaque page. Le guide de configuration Shopify détaille chaque étape.

2. Ajoutez le pixel de checkout

   Dans Shopify admin › Settings › Customer events, ajoutez un pixel personnalisé nommé ROASaurus et collez l’extrait de votre page Tracking & platforms. Il déclenche le pixel TikTok dans le checkout, y compris la copie navigateur de l’achat.

3. Créez un jeton d’accès

   Dans TikTok Events Manager, ouvrez votre pixel et générez un jeton d’accès à l’Events API dans ses réglages. Copiez le jeton et le code du pixel.

4. Ajoutez le pixel TikTok dans ROASaurus

   Allez dans Tracking & platforms, cliquez sur Add pixel sur la carte TikTok et remplissez Pixel code et Events API access token. Laissez Also load the browser pixel (recommended, deduplicated) coché, pour que les événements du navigateur et du serveur partagent leurs identifiants.

5. Ajoutez les dépenses (facultatif)

   Renseignez Advertiser ID for spend et un Marketing API token. ROASaurus importe alors les dépenses TikTok, pour que les campagnes TikTok affichent le ROAS et le CPA à côté de vos autres canaux.

6. Testez, puis passez en production

   Envoyez une commande de test avec un code d’événement de test comme décrit plus haut, puis retirez le code.

Avec Respect visitor consent activé, ce qui est le réglage par défaut, ROASaurus suit le choix de l’acheteur dans la bannière de cookies de Shopify. Quand un acheteur refuse les cookies marketing, ROASaurus ne charge pas le pixel TikTok pour lui, ne définit aucun identifiant visiteur (ses clics ne sont donc pas rattachés à lui) et n’envoie pas ses événements de navigation à TikTok. Sa commande payée est quand même envoyée à l’Events API depuis le serveur, avec les données de commande hachées ainsi que l’adresse IP et le user agent de la commande, mais sans ttclid ni _ttp. Le guide du consentement et de la confidentialité explique ce qui est stocké et envoyé.

Une fois les dépenses synchronisées, les campagnes TikTok apparaissent dans les rapports d’attribution à côté de Meta, et l’analyse créative ajoute les statistiques vidéo TikTok par publicité. ROASaurus attribue les commandes aux clics publicitaires et aux UTM qu’il a enregistrés, et ne compte les conversions après vue que comme une estimation modélisée dans son modèle Clicks & views : ses totaux diffèrent donc généralement de ceux de TikTok Ads Manager. Pour les autres plateformes côté serveur, consultez le guide de la Pinterest Conversions API et le guide de la Meta Conversions API.

Sources

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok’s Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

Dans ROASaurus

• Intégration TikTok
• Le suivi côté serveur dans ROASaurus
• Aide : éviter le double comptage
• Aide : configurer ROASaurus sur Shopify

À lire aussi