Conversions API di OpenAI per WooCommerce: inviare gli acquisti lato server

Nel browser, il Measurement Pixel invia visualizzazioni di prodotto, aggiunte al carrello, inizi di checkout e l'acquisto. Quando WooCommerce conferma un ordine pagato, l'acquisto parte anche dal tuo server tramite la OpenAI Conversions API, con lo stesso event ID, così OpenAI può contarlo una sola volta.

Il Measurement Pixel gira nel browser di chi acquista. È l'unico punto da cui si vedono le visualizzazioni di prodotto e l'attività sul carrello, ma significa anche che un evento va perso ogni volta che la pagina o lo script non arrivano fino in fondo:

• Estensioni che bloccano i contenuti o strumenti per la privacy impediscono il caricamento dello script del pixel.
• Il cliente chiude la scheda dopo aver pagato, prima che si carichi la pagina di conferma dell'ordine.
• Il pagamento viene confermato più tardi (bonifico, alcuni gateway con reindirizzamento), quando il cliente non è più sul sito.
• Un caricamento lento o fallito della pagina fa perdere la richiesta.

In tutti questi casi WooCommerce registra comunque l'ordine. Un evento di acquisto lato server parte da quell'ordine, quindi nessuno di questi casi ne impedisce l'invio.

Il tuo server fa una richiesta HTTPS autenticata a OpenAI con uno o più eventi. La richiesta è indirizzata tramite il Pixel ID e autorizzata con una chiave della Conversions API, entrambi generati nella scheda delle conversioni di Ads Manager (documentazione della OpenAI Conversions API, in inglese, come tutta la documentazione di OpenAI citata in questa guida).

Invialo quando WooCommerce segna l'ordine come pagato, non quando si carica la pagina di conferma dell'ordine. Legare l'evento allo stato dell'ordine invece che a una visualizzazione di pagina significa che:

• Parte una sola volta per ordine, anche se la pagina di ringraziamento viene ricaricata più volte.
• Con i metodi di pagamento differiti l'acquisto parte quando il pagamento viene davvero confermato.
• Gli ordini non pagati, falliti o abbandonati non vengono segnalati come acquisti.

1. Checkout completato

   Ordine creato in WooCommerce

2. Pagamento confermato

   L'ordine raggiunge uno stato pagato

3. Acquisto inviato

   order_created dal tuo server

4. Esito registrato

   Accettato, ritentato o fallito

Se un acquisto viene inviato sia dal browser sia dal server, OpenAI deve poter capire che si tratta di un solo acquisto. Secondo la documentazione di OpenAI, per la deduplica vengono usati il Pixel ID, l'event_name e l'id: per ogni chiave corrispondente vale il primo evento ricevuto, mentre i duplicati successivi vengono ignorati.

L'event ID deve quindi essere identico sui due canali. Su WooCommerce il modo affidabile per ottenerlo è ricavarlo dall'ordine, che conoscono sia la pagina di conferma sia il server, invece di generare nel browser un ID casuale che il server non vedrà mai. La guida pixel o Conversions API spiega come si incastrano i due canali.

OpenAI rifiuta gli eventi fuori da una certa finestra temporale: secondo la sua documentazione, il timestamp deve cadere negli ultimi 7 giorni e non oltre 10 minuti nel futuro. Per un negozio ci sono due conseguenze:

• Invia l'orario originale dell'acquisto, non quello del tentativo: altrimenti, a ogni nuovo tentativo, l'acquisto risulterebbe avvenuto più tardi del reale.
• Risolvi in fretta gli invii falliti. Un ordine con un orario d'acquisto più vecchio di 7 giorni non può più essere inviato.

L'API accetta anche batch fino a 1.000 eventi, e la documentazione precisa che se un solo evento del batch fallisce, fallisce l'intero batch: un ordine malformato può bloccare anche gli altri, se l'implementazione raggruppa gli eventi senza cura.

La documentazione di OpenAI chiede di riutilizzare lo stesso ID quando ritenti l'invio o mandi la stessa conversione tramite un'altra integrazione. Non pubblica però un calendario dei tentativi, quindi la strategia spetta all'implementazione. Una strategia sensata distingue:

Qualunque sia la strategia, un errore deve essere visibile da qualche parte. Senza un registro per ordine, un'integrazione rotta sembra in tutto e per tutto una settimana di vendite fiacca.

L'invio lato server non è un modo per aggirare il consenso. Il pixel stesso non invia ping di misurazione quando il consenso è negato (documentazione del Measurement Pixel), e un acquisto lato server deve rispettare lo stato di consenso registrato per quell'ordine. Su WordPress, la WordPress Consent API è il modo più diffuso con cui un banner dei cookie condivide quello stato con gli altri plugin.

Pixel for ChatGPT Ads è un plugin WooCommerce che invia lato server solo l'acquisto. Ecco cosa fa in ciascuno dei punti visti sopra:

Ingrandisci lo screenshot

Chiudi

Visualizzazioni di prodotto, aggiunte al carrello e inizi di checkout restano eventi del browser. La pagina Il pixel di ChatGPT Ads per WooCommerce elenca ogni evento e da dove parte.