Funzionamento del tracking¶

Architettura a doppio canale¶

Ogni evento di tracciamento viene attivato tramite due canali simultaneamente:

1. Conversions API (CA) — PHP/lato server, inviato direttamente all'API Graph di Facebook tramite il Facebook Business SDK. Si attiva all'interno degli hook PS, immediatamente sulla richiesta HTTP che lo innesca.
2. Facebook Pixel (JS) — chiamate fbq() lato browser, iniettate tramite uno script frontend compilato con Vite. Lo script esegue il polling del server per gli eventi in coda e li attiva con fbq().

Entrambi i canali portano lo stesso event_id in modo che Facebook li deduplichi automaticamente.

Flusso degli eventi¶

1. Si attiva un hook PS (es. actionCartUpdateQuantityBefore)
   └── CAEventBuilder::addToCart() costruisce l'evento
       ├── Imposta event_name, event_time, event_id (UUID), event_source_url, user_data, custom_data
       └── CAEventBuilder::sendEvent()
           ├── Invia l'evento all'API Graph di Facebook (canale CA)
           └── Persiste la riga FbpEvent nella tabella fbp_event
               ├── ca_sent = 1
               ├── js_sent = 0
               └── js_event = payload JSON per la chiamata fbq() lato browser

2. Il browser carica la pagina, il JS frontend si avvia
   └── Esegue il polling di ConsumerController (?action=poll)
       └── Restituisce: { pixel: { pixel_id, external_id }, events: [ { id, event_type, js_event } ] }
           └── Per ogni evento:
               ├── fbq('track', event_type, js_event_data)  ← attiva il pixel
               └── Chiama ConsumerController (?action=confirm&id_fbp_event=N)
                   └── Marca fbp_event.js_sent = 1

Contesto ospite¶

Ad ogni inizializzazione del front controller (actionFrontControllerInitAfter), il modulo cattura:

• User agent — $_SERVER['HTTP_USER_AGENT']
• IP client — tramite Tools::getRemoteAddr()
• Cookie _fbp — ID browser Facebook, persistente tra le sessioni
• Cookie _fbc — ID clic Facebook, impostato quando un utente arriva tramite un annuncio Facebook

Questi valori vengono memorizzati in fbp_guest_context indicizzati per id_guest e allegati allo user_data di ogni evento CA. Se l'utente è autenticato, nome, email e data di nascita vengono anche hashati e inclusi.

Rimappatura dell'ID ospite¶

PrestaShop può rinnovare id_guest durante il checkout (es. alla creazione dell'ordine). Quando ciò accade, gli eventi in coda sotto il vecchio ID ospite non verrebbero mai interrogati dal browser (che ora ha il nuovo id_guest).

Il modulo gestisce questo in due punti:

1. hookActionFrontControllerInitAfter — se _fbp viene visto associato a un id_guest diverso, gli eventi in attesa per l'ospite obsoleto vengono rimappati all'ospite corrente.
2. ConsumerController::remapStaleGuestEvents() — una rete di sicurezza: esegue la stessa logica di rimappatura prima della query di polling, catturando i casi in cui il rinnovo è avvenuto dopo l'attivazione dell'hook.

Formattazione dell'ID prodotto¶

L'ID prodotto usato negli eventi di tracciamento segue i flag di formato ID (cs_id_format) e usa riferimento (cs_use_reference_id) delle impostazioni pixel:

• Predefinito: {id} → "42" (ID prodotto) o "42-7" (ID prodotto + ID combinazione quando le combinazioni sono esportate)
• Template personalizzato: es. ps_{id} → "ps_42"
• Modalità riferimento: {ref} → valore del campo riferimento del prodotto

Questo deve corrispondere a ciò che usa l'esportazione del catalogo, in modo che gli eventi di tracciamento facciano riferimento agli stessi ID del feed.

Deduplicazione¶

A ogni evento viene assegnato un event_id univoco (generato da Utilities::createEventId()). Lo stesso ID viene usato sia per l'evento CA che per l'evento JS pixel memorizzato in fbp_event.event_id. Facebook lo usa per deduplicare.

Tabella fbp_event¶