Pinterest Conversions API pour Shopify : guide de configuration

La Pinterest Conversions API est la méthode serveur à serveur de Pinterest pour envoyer des événements de conversion. Votre boutique, ou un outil comme ROASaurus, envoie des événements tels que les achats directement à votre compte publicitaire Pinterest, au lieu de s’appuyer uniquement sur le Pinterest Tag dans le navigateur de l’acheteur. Pinterest utilise ces données pour le reporting des conversions, l’optimisation des campagnes et le ciblage.

Ce guide couvre l’API v5 et les événements qu’elle accepte, l’identifiant de clic epik, la façon dont les données client sont hachées, le fonctionnement de la déduplication avec le Pinterest Tag, la manière de tester, et comment tout configurer sur Shopify.

Qu’est-ce que la Pinterest Conversions API ?

Le Pinterest Tag est un script dans le navigateur de l’acheteur. La Conversions API fait le même travail depuis un serveur. Dans la version 5 de l’API, vous envoyez les événements au point de terminaison des événements de votre compte publicitaire, autorisé par un jeton d’accès de conversion que vous créez dans Pinterest Ads Manager. Chaque événement indique où il a eu lieu : pour une boutique en ligne, la source d’action est web.

Pinterest demande aux annonceurs qui utilisent aussi le Tag d’éviter de compter une conversion deux fois, en passant un event_id avec chaque événement. Il demande aussi les événements en temps réel, ou au plus une heure après leur survenue.

Sur Shopify, une connexion serveur a un avantage net : les achats viennent de la commande elle-même. Shopify signale chaque commande payée à ROASaurus par webhook, et ROASaurus l’envoie à Pinterest peu après le paiement, que le Tag se soit déclenché ou non dans le navigateur. Le guide du suivi côté serveur sur Shopify explique l’idée plus en détail.

Quels événements la Pinterest Conversions API accepte-t-elle ?

Pinterest a une liste fixe de noms d’événements standard, écrits en minuscules avec des tirets bas, comme page_visit, add_to_cart et checkout. Vous pouvez aussi définir jusqu’à 15 types d’événements personnalisés par annonceur. ROASaurus associe les cinq événements de parcours d’achat de Shopify ainsi :

Le nom peut prêter à confusion. Le checkout de Pinterest est l’achat terminé, pas le début du checkout. Le début du checkout est un événement distinct, initiate_checkout.

Pour l’événement de checkout, Pinterest recommande d’envoyer la valeur, la devise, l’identifiant de commande, les identifiants de contenu et le nombre d’articles. ROASaurus envoie les cinq, plus la quantité et le prix de chaque article. Pinterest demande la valeur avant taxes et livraison. Sur Shopify, ROASaurus envoie exactement cela : le total de la commande moins les taxes et la livraison, depuis le serveur et depuis la balise du navigateur. Quand une plateforme de boutique en ligne ne communique pas séparément les taxes et la livraison, ROASaurus envoie le total de la commande.

Comment Pinterest associe-t-il un événement à une personne ?

Chaque événement porte des données utilisateur. Pinterest exige au moins l’un de ces trois éléments : une adresse e-mail hachée, un identifiant publicitaire mobile haché, ou l’adresse IP avec le user agent. Une boutique en ligne n’a pas d’identifiant publicitaire ; il lui faut donc l’e-mail, ou l’adresse IP et le user agent. ROASaurus ignore un événement qui n’a ni l’un ni l’autre, au lieu d’en envoyer un que Pinterest ne peut pas utiliser.

L’identifiant de clic epik

L’identifiant de clic Pinterest peut venir de deux endroits : un paramètre epik dans l’URL de la page d’arrivée, ou le cookie _epik sur votre domaine. Le guide de l’API de Pinterest recommande de transmettre la valeur du cookie _epik, car elle fonctionne encore quand le paramètre d’URL est absent ou supprimé, ce qui donne une meilleure couverture.

ROASaurus lit les deux sur votre boutique, en utilisant le paramètre d’URL quand un nouveau clic en apporte un et le cookie sinon. Il enregistre l’identifiant de clic avec le visiteur et l’envoie dans le champ click_id de chaque événement serveur, y compris l’achat. Les visites avec un epik comptent comme des visites Pinterest dans les rapports d’attribution de ROASaurus.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Comment fonctionne la déduplication avec le Pinterest Tag ?

Si le Tag et l’API signalent tous deux un achat, Pinterest reçoit deux événements pour une seule commande. Pour les traiter comme un seul, il lui faut le même identifiant des deux côtés : l’identifiant d’événement dans le Tag doit correspondre à l’event_id de l’événement serveur. Pinterest garde le premier événement qu’il reçoit et supprime les doublons qui arrivent dans les 48 heures.

ROASaurus construit l’identifiant d’achat à partir de l’identifiant de commande Shopify. L’achat de la commande 5512345678901 a l’identifiant d’événement order-5512345678901, dans le Tag qui se déclenche au checkout comme dans l’événement serveur.

Les cinq événements sont dédupliqués

Chaque événement du parcours d’achat dans ROASaurus a un identifiant d’événement, utilisé par le Tag dans le navigateur et par l’événement serveur. Le Tag utilise les noms propres à Pinterest pour les mêmes événements : pagevisit, viewcontent, addtocart, initiatecheckout et checkout, qui correspondent à page_visit, view_content, add_to_cart, initiate_checkout et checkout dans l’API. Quand les deux fonctionnent, Pinterest garde donc un exemplaire de chaque visite de page, consultation de produit, ajout au panier, début de checkout et achat.

Vous pouvez l’utiliser de deux façons :

• Tag et Conversions API ensemble. Le Tag ajoute des signaux du navigateur, le serveur complète ce que le Tag manque, et Pinterest fusionne les copies.
• Utilisez l’API sans le Tag. Laissez le Tag ID vide ou désactivez Also load the browser tag. Chaque événement est alors envoyé une seule fois, depuis le serveur uniquement.

L’article d’aide sur le double comptage couvre les mêmes vérifications pour les autres plateformes publicitaires.

Comment tester la Pinterest Conversions API ?

L’API a un indicateur de test. Les requêtes envoyées avec test=true vont vers un bac à sable : Pinterest les traite comme des données de test et ne les utilise ni pour le reporting ni pour l’optimisation.

1. Activez le mode test

   Dans ROASaurus, modifiez le pixel Pinterest sous Tracking & platforms et cochez Test mode (events show under Test events, max 20). Chaque événement serveur est alors envoyé avec test=true. Pinterest traite au maximum 20 événements de test par lot.

2. Passez une commande de test

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

3. Lisez le résultat

   Ouvrez l’Event log. Pinterest peut répondre HTTP 200 alors qu’un événement d’une requête a échoué ; ROASaurus vérifie donc le statut de chaque événement et y affiche les échecs.

4. Désactivez le mode test

   Décochez le mode test, pour que les événements comptent dans le reporting et l’optimisation.

5. Vérifiez Events Overview

   Dans Pinterest Ads Manager, ouvrez la page Events Overview. Elle montre les événements reçus et les conversions dédupliquées. Pinterest recommande de viser un Event Quality Score de niveau Good.

Comment configurer la Pinterest Conversions API sur Shopify avec ROASaurus

Il vous faut une boutique Shopify avec l’application ROASaurus et un accès à Pinterest Ads Manager. La page de l’intégration Pinterest 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. Il capture epik et le cookie _epik sur chaque page. Le guide de configuration Shopify détaille chaque étape.

2. Créez un jeton d’accès de conversion

   Dans Pinterest Ads Manager, allez dans Conversions et créez un jeton d’accès de conversion. Notez l’identifiant de votre compte publicitaire.

3. Ajoutez le pixel Pinterest dans ROASaurus

   Allez dans Tracking & platforms, cliquez sur Add pixel sur la carte Pinterest et remplissez Ad account ID et Conversion access token.

4. Ajoutez votre Tag ID

   Pour la déduplication avec le Tag, renseignez Pinterest Tag ID et laissez Also load the browser tag coché. Sans Tag ID, ROASaurus envoie uniquement des événements serveur et ne charge pas le Tag.

5. 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 l’événement checkout du Tag dans le checkout de Shopify, avec l’identifiant de commande comme event_id.

6. Choisissez les événements serveur, puis testez

   Choisissez les événements serveur souhaités et testez avec le mode test avant de passer en production.

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 Pinterest Tag 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 à Pinterest. Sa commande payée est quand même envoyée à la Conversions 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 identifiant de clic. Le guide du consentement et de la confidentialité explique ce qui est stocké et envoyé.

Connectez votre compte publicitaire Pinterest sous Setup › Ad spend et ROASaurus récupère les dépenses de campagne toutes les heures : vous voyez ainsi le ROAS Pinterest et le bénéfice après publicité dans l’analyse du bénéfice. Le guide de la TikTok Events API couvre la même configuration pour TikTok, où chaque événement qui passe par les deux voies est dédupliqué.

Sources

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

Dans ROASaurus

• Intégration Pinterest
• Le suivi côté serveur dans ROASaurus
• Aide : éviter le double comptage

À lire aussi