Fonctionnement du suivi¶

Architecture double canal¶

Chaque événement de suivi est déclenché via deux canaux simultanément :

1. API Conversions (CA) — PHP/côté serveur, envoyé directement à l'API Graph de Facebook via le SDK Facebook Business. Se déclenche dans les hooks PS, immédiatement lors de la requête HTTP déclencheuse.
2. Facebook Pixel (JS) — appels fbq() côté navigateur, injectés via un script frontend compilé avec Vite. Le script sonde le serveur pour les événements en attente et les déclenche avec fbq().

Les deux canaux portent le même event_id pour que Facebook les déduplique automatiquement.

Flux d'événements¶

1. Un hook PS se déclenche (ex. actionCartUpdateQuantityBefore)
   └── CAEventBuilder::addToCart() construit l'événement
       ├── Définit event_name, event_time, event_id (UUID), event_source_url, user_data, custom_data
       └── CAEventBuilder::sendEvent()
           ├── Envoie l'événement à l'API Graph de Facebook (canal CA)
           └── Persiste la ligne FbpEvent dans la table fbp_event
               ├── ca_sent = 1
               ├── js_sent = 0
               └── js_event = payload JSON pour l'appel fbq() côté navigateur

2. Le navigateur charge la page, le JS frontend démarre
   └── Sonde ConsumerController (?action=poll)
       └── Retourne : { pixel: { pixel_id, external_id }, events: [ { id, event_type, js_event } ] }
           └── Pour chaque événement :
               ├── fbq('track', event_type, js_event_data)  ← déclenche le pixel
               └── Appelle ConsumerController (?action=confirm&id_fbp_event=N)
                   └── Marque fbp_event.js_sent = 1

Contexte de l'invité¶

À chaque initialisation du front controller (actionFrontControllerInitAfter), le module capture :

• User agent — $_SERVER['HTTP_USER_AGENT']
• IP client — via Tools::getRemoteAddr()
• Cookie _fbp — ID navigateur Facebook, persisté entre les sessions
• Cookie _fbc — ID de clic Facebook, défini quand un utilisateur arrive via une annonce Facebook

Ces valeurs sont stockées dans fbp_guest_context indexées par id_guest et attachées au user_data de chaque événement CA. Si l'utilisateur est connecté, le nom, l'email et la date de naissance sont également hachés et inclus.

Remapping de l'ID invité¶

PrestaShop peut renouveler id_guest lors du paiement (ex. à la création de la commande). Lorsque cela se produit, les événements en attente sous l'ancien ID invité ne seraient jamais sondés par le navigateur (qui a maintenant le nouveau id_guest).

Le module gère cela à deux endroits :

1. hookActionFrontControllerInitAfter — si _fbp est vu associé à un id_guest différent, les événements en attente pour l'invité obsolète sont remappés vers l'invité actuel.
2. ConsumerController::remapStaleGuestEvents() — un filet de sécurité : exécute la même logique de remapping avant la requête de sondage, capturant les cas où le renouvellement s'est produit après le déclenchement du hook.

Formatage de l'ID produit¶

L'ID produit utilisé dans les événements de suivi suit les indicateurs de format d'ID (cs_id_format) et utiliser la référence (cs_use_reference_id) des paramètres du pixel :

• Par défaut : {id} → "42" (ID produit) ou "42-7" (ID produit + ID déclinaison quand les déclinaisons sont exportées)
• Modèle personnalisé : ex. ps_{id} → "ps_42"
• Mode référence : {ref} → valeur du champ référence du produit

Cela doit correspondre à ce qu'utilise l'export du catalogue, pour que les événements de suivi référencent les mêmes IDs que le flux.

Déduplication¶

Chaque événement reçoit un event_id unique (généré par Utilities::createEventId()). Le même ID est utilisé à la fois pour l'événement CA et l'événement JS pixel stocké dans fbp_event.event_id. Facebook l'utilise pour dédupliquer.

Table fbp_event¶