X Pixel + Web Conversions API — Documentation

Suivez les conversions X Ads dans PrestaShop avec les événements Pixel côté navigateur et, en option, les événements serveur via Web Conversions API.

Ce qui est suivi

• PageView via la configuration de base du X Pixel.
• ViewContent sur les pages produit.
• AddToCart via le bus d’événements du panier PrestaShop, avec détection de bouton en fallback pour les thèmes plus anciens.
• AddToWishlist via les bus d’événements de wishlist courants et les gestionnaires de clics.
• StartCheckout lorsque la page de démarrage du checkout est détectée.
• Search lorsque le visiteur utilise la page de recherche PrestaShop.
• SignUp après la création d’un compte client.
• Purchase sur la confirmation de commande et la validation de commande.
• Règles personnalisées de clic, d’URL, de contrôleur et d’événement DOM.

Compatibilité

Compatible avec PrestaShop 1.6 à 9.0 (latest) et PHP 7.1+. Nous continuons à prendre en charge les prochaines versions de PrestaShop.

Configuration requise

1. Créez ou ouvrez votre Event Source dans X Ads Manager.
2. Copiez la X Pixel ID dans le module.
3. Activez le suivi côté navigateur.
4. Ajoutez les Event IDs pour les événements de conversion que vous souhaitez envoyer. Purchase Event ID est obligatoire lorsque le suivi des achats est activé.
5. Enregistrez les paramètres et consultez le panneau de diagnostic.

La Pixel ID accepte les lettres, les chiffres, les underscores et les tirets :

abc123_pixel-id

Le module utilise ces hooks PrestaShop :

displayHeader
displayOrderConfirmation
actionValidateOrder
actionCustomerAccountAdd

Paramètres principaux

Le module stocke ces options pour le suivi et l’envoi via l’API :

ENABLED=1
PIXEL_ID=your_x_pixel_id
EXCLUDE_EMPLOYEES=1
RESPECT_CONSENT=1

TRACK_PAGEVIEW=1
TRACK_VIEWCONTENT=1
TRACK_ADDTOCART=1
TRACK_STARTCHECKOUT=1
TRACK_PURCHASE=1
TRACK_SEARCH=1
TRACK_ADDTOWISHLIST=1
TRACK_SIGNUP=1
TRACK_CUSTOM_EVENTS=0

Les Event IDs sont configurés par événement :

EVENT_ID_VIEWCONTENT=
EVENT_ID_ADDTOCART=
EVENT_ID_STARTCHECKOUT=
EVENT_ID_PURCHASE=
EVENT_ID_SEARCH=
EVENT_ID_ADDTOWISHLIST=
EVENT_ID_SIGNUP=

Les Event IDs peuvent contenir des lettres, des chiffres, des underscores et des traits d’union :

tw-viewcontent-123
tw-addtocart-123
tw-purchase-123

Consentement et trafic des employés

Lorsque Respect cookie consent est activé, le suivi attend le consentement marketing si mprcookiesrevolution ou mprcookiebanner est actif.

Le module lit ces signaux de consentement :

mprcr_consent=marketing:1
mprcookie_consent=granted

Si Exclude employees est activé, le module n’injecte pas le suivi lorsqu’un employé connecté au back-office parcourt le front office.

Web Conversions API

Activez l’API uniquement après avoir obtenu des identifiants OAuth 1.0a Ads API :

CAPI_ENABLED=1
CAPI_CONSUMER_KEY=your_api_key
CAPI_CONSUMER_SECRET=your_api_secret
CAPI_ACCESS_TOKEN=your_access_token
CAPI_ACCESS_SECRET=your_access_token_secret
CAPI_API_VERSION=12
CAPI_SEND_IP_UA=1
CAPI_BATCH_LIMIT=20

Le module envoie les payloads de conversion en file d’attente à X Ads API :

https://ads-api.x.com/12/measurement/conversions/{pixel_id}

Les événements en file d’attente sont traités par la tâche cron du module :

send_x_conversions
schedule: every:300

La limite de lot de la file d’attente doit être comprise entre 1 et 100. La valeur par défaut est :

CAPI_BATCH_LIMIT=20

Capture de twclid

Le script navigateur capture twclid depuis les URL de clic des annonces X et le stocke pour faire correspondre les événements API :

https://www.example.com/product-name?twclid=abc123

Le nom du cookie stocké est :

mprxpix_twclid

Pour le test API dans l’administration, utilisez un vrai twclid provenant d’un clic sur une annonce X. Le champ de test accepte les lettres, les chiffres, les points, les underscores, les deux-points et les tirets :

CAPI_TEST_TWCLID=abc.123_test-id

Règles d’événements personnalisés

Les événements personnalisés sont saisis au format JSON dans Custom event rules. Chaque règle nécessite un nom d’événement et x_event_id.

Exemple de règle de clic :

[
  {
    "event": "GalleryBrowse",
    "x_event_id": "tw-gallery-123",
    "trigger": "click",
    "selector": ".product-images img,.images-container img",
    "params": {
      "property": "product_gallery"
    },
    "capi": true
  }
]

Les déclencheurs pris en charge sont :

click
url
controller
event

Exemple de règle URL :

[
  {
    "event": "LandingPageVisit",
    "x_event_id": "tw-landing-123",
    "trigger": "url",
    "contains": ["/promo", "utm_campaign=x"],
    "params": {
      "property": "campaign_landing"
    },
    "once": true,
    "capi": true
  }
]

Exemple de règle de contrôleur :

[
  {
    "event": "CheckoutPageView",
    "x_event_id": "tw-checkout-123",
    "trigger": "controller",
    "controllers": ["order"],
    "params": {
      "property": "checkout"
    },
    "capi": true
  }
]

Exemple de règle d’événement DOM :

[
  {
    "event": "ConfiguratorComplete",
    "x_event_id": "tw-configurator-123",
    "trigger": "event",
    "dom_event": "mprxpix:custom",
    "params": {
      "property": "configurator"
    },
    "capi": true
  }
]

Pour les règles de clic, le module lit aussi des paramètres supplémentaires depuis les attributs data HTML :

<button
  class="track-x-demo"
  data-x-param-product_id="123"
  data-x-param-product_name="Demo product"
  data-mprxpix-param-property="custom_button">
  Track event
</button>

Noms des événements navigateur

Le module normalise les noms d’événements courants avant de les envoyer :

ViewContent -> viewcontent
AddToCart -> addtocart
StartCheckout -> startcheckout
InitiateCheckout -> startcheckout
Purchase -> purchase
CompletePayment -> purchase
Search -> search
AddToWishlist -> addtowishlist
SignUp -> signup
CompleteRegistration -> signup

Diagnostic

La page des paramètres inclut des diagnostics Web Conversions API :

• Compteurs de file d’attente pour les événements en attente, en cours d’envoi, envoyés et échoués.
• Contrôles de préparation pour Pixel ID, le suivi navigateur, Purchase Event ID, les identifiants OAuth, les règles personnalisées, la capture de twclid et la table de file d’attente.
• Lignes d’événements récents avec le nom de l’événement, le statut, les tentatives, le code HTTP, la date de mise à jour et la dernière erreur.
• Send API probe pour tester les identifiants avec un vrai twclid.
• Retry failed events pour remettre les événements échoués dans la file d’attente.

Checklist pratique de configuration

1. Saisissez PIXEL_ID.
2. Activez ENABLED.
3. Gardez RESPECT_CONSENT activé si votre boutique utilise le consentement aux cookies.
4. Gardez EXCLUDE_EMPLOYEES activé lorsque vous testez depuis le back-office.
5. Ajoutez EVENT_ID_PURCHASE avant d’activer le suivi des achats.
6. Ajoutez les autres Event IDs que vous souhaitez utiliser pour l’optimisation X Ads.
7. Activez CAPI_ENABLED uniquement après avoir ajouté les quatre identifiants OAuth.
8. Utilisez le panneau de diagnostic pour vérifier la file d’attente et le test API.