TikTok Events API per Shopify: configurazione e deduplicazione

La TikTok Events API è la connessione server-to-server di TikTok per i dati di conversione. Invece di affidarsi solo al pixel TikTok nel browser dell’acquirente, il tuo negozio, o uno strumento come ROASaurus, invia eventi come gli acquisti direttamente a TikTok. TikTok consiglia di eseguire la Events API accanto al pixel e di deduplicare i due con un event_id condiviso.

Questa guida tratta cosa invia la Events API da un negozio Shopify, i nomi degli eventi Purchase e CompletePayment, il click id e il cookie su cui TikTok effettua l’associazione, come funziona la deduplicazione, come testare in TikTok Events Manager e come configurare tutto in ROASaurus.

Che cos’è la TikTok Events API?

Il pixel TikTok è uno script sul tuo negozio. Attiva gli eventi dal browser dell’acquirente, quindi conta solo ciò che accade mentre lo script si carica ed è in esecuzione. Un ad blocker, un errore di script o un acquirente che chiude la scheda prima che si carichi la conferma dell’ordine possono fermarlo.

La Events API invia lo stesso tipo di evento da un server. Su Shopify, la registrazione più affidabile di un acquisto è l’ordine stesso. Shopify segnala ogni ordine pagato tramite webhook, che lo script del browser sia stato eseguito o meno. È l’idea alla base del tracciamento server-side su Shopify.

I due non sono alternative. Il consiglio di TikTok è di condividere gli eventi attraverso entrambi, mantenerli coerenti lungo il percorso d’acquisto e lasciare che TikTok rimuova i duplicati.

Quali eventi invia ROASaurus a TikTok?

Quattro momenti in un negozio Shopify contano per l’ottimizzazione di TikTok: la visualizzazione di un prodotto, l’aggiunta al carrello, l’avvio del checkout e l’acquisto. ROASaurus li invia tutti e quattro alla Events API e fa scattare gli stessi quattro tramite il pixel TikTok, con gli stessi event id. Le visualizzazioni di pagina passano solo dal pixel.

Nelle impostazioni del pixel puoi deselezionare gli eventi server che non vuoi inviare, e aggiungere filtri come un paese o un valore minimo dell’ordine.

Purchase o CompletePayment?

TikTok ha rinominato il suo evento di acquisto. Il nome attuale è Purchase. Il vecchio nome, CompletePayment, funziona ancora: TikTok converte i nomi legacy dal proprio lato, li mostra con il nuovo nome nei report, nei pubblici e nell’ottimizzazione, e dice che CompletePayment sarà supportato a tempo indeterminato. TikTok chiede che le nuove configurazioni del pixel usino Purchase.

ROASaurus invia CompletePayment, nel pixel e nella Events API. In TikTok Events Manager e Ads Manager, quegli eventi compaiono come Purchase. Per la deduplicazione, conta che entrambe le copie di un acquisto usino lo stesso nome evento, e lo fanno.

Come fa TikTok ad associare un evento a un acquirente?

Un evento aiuta le tue campagne solo se TikTok può collegarlo alla persona che ha visto o cliccato l’annuncio. TikTok chiama questi identificatori chiavi di associazione, e la sua guida alla Events API chiede di restituire tutte le chiavi di associazione rilevanti per aumentare i tassi di associazione. Events Manager mostra il risultato come punteggio Event Match Quality, una media ponderata di quanto spesso è presente ogni chiave di associazione.

TikTok osserva che il pixel condivide per impostazione predefinita l’indirizzo IP e lo user agent, ma la Events API richiede che vengano aggiunti a mano. ROASaurus li prende dalla sessione di checkout dell’acquirente, o dall’ordine se non c’era una sessione. Su Shopify altre due chiavi richiedono attenzione.

ttclid: il click id di TikTok

Quando un acquirente clicca un annuncio TikTok, TikTok aggiunge ttclid all’URL della pagina di atterraggio. Se il tuo negozio non lo salva su quella prima pagina, è perso nel momento in cui arriva l’ordine, diverse pagine dopo. ROASaurus legge ttclid sulla pagina di atterraggio, lo memorizza con il visitor id, lo scrive nel carrello Shopify e lo aggiunge all’evento server quando arriva l’ordine.

_ttp: il cookie del pixel

Il cookie _ttp è un cookie first-party che il pixel TikTok usa sul tuo dominio. ROASaurus lo legge sul negozio e al checkout e lo invia come ttp nell’evento server. È un altro motivo per tenere attivo il pixel accanto alla Events API.

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "user": {
      "email": "a3f1…9c2e",
      "phone": "7b40…11d8",
      "external_id": "e05c…4a7f",
      "ttclid": "E.C.P.v3…",
      "ttp": "2Xb7…",
      "ip": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; …)"
    },
    "page": { "url": "https://example-store.com/checkouts/…/thank-you" },
    "properties": {
      "currency": "USD",
      "value": 84,
      "content_type": "product",
      "contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
      "order_id": "5512345678901"
    }
  }]
}

Come funziona la deduplicazione?

Quando il pixel e la Events API segnalano entrambi lo stesso acquisto, TikTok riceve due eventi per un solo ordine. Per tenerne uno solo, TikTok ha bisogno che due valori siano identici in entrambe le copie: il nome dell’evento e l’event_id. TikTok registra poi la prima copia che riceve per misurazione e report, così l’ordine conta una volta. Funziona per le copie corrispondenti che arrivano entro una finestra di 48 ore dalla prima.

ROASaurus costruisce l’event id di un acquisto dall’id dell’ordine Shopify. L’acquisto dell’ordine 5512345678901 ha l’event id order-5512345678901, nel pixel del checkout e sul server. Gli eventi del negozio, come le visualizzazioni di prodotto e le aggiunte al carrello, ricevono un id casuale quando avvengono, e la copia del browser e quella del server lo condividono.

Ecco cosa significa per i numeri. Prendi un negozio di esempio con 200 ordini in una settimana. Il pixel scatta per 150 di essi. Gli altri 50 acquirenti hanno usato un ad blocker, rifiutato i cookie di marketing o se ne sono andati prima che la pagina di conferma si caricasse. La Events API li invia tutti e 200.

Il 350 è il numero che deve preoccuparti. Farebbe risultare il conteggio degli acquisti di TikTok, e il ROAS che ne deriva, più alto del 75% rispetto alla realtà, perché 350 ÷ 200 = 1.75. TikTok usa questi eventi anche per l’ottimizzazione e il targeting, quindi le sue offerte imparerebbero da 150 acquisti che non sono avvenuti.

Perché su Shopify gli acquisti vengono contati due volte?

Il doppio conteggio avviene quando TikTok riceve due copie di un acquisto che non riesce ad associare. Controlla queste cause prima di fidarti di un’impennata degli acquisti su TikTok:

• Due strumenti inviano lo stesso pixel. L’app del canale di vendita TikTok su Shopify può inviare eventi anche per il tuo pixel. I suoi event id non corrispondono agli id usati da ROASaurus, quindi TikTok conta ogni ordine due volte. Scollega il pixel in quell’app.
• Il pixel è anche nel codice del tema. Uno snippet del pixel incollato nel tema attiva i propri eventi senza i tuoi event id. Rimuovilo e lascia che sia un solo strumento a caricare il pixel.
• Un lato non ha event_id. Un acquisto del server senza un event_id, o con un nuovo id casuale, non può essere associato alla copia del pixel.
• I nomi degli eventi sono diversi. TikTok deduplica solo eventi identici. Entrambe le copie di un acquisto devono usare lo stesso nome evento.

L’articolo di aiuto sul doppio conteggio ripercorre gli stessi controlli per Meta e le altre piattaforme.

Come testare la Events API in TikTok Events Manager?

TikTok Events Manager ha una scheda Test events per gli eventi sia del browser sia del server. Usala prima di fare affidamento sui dati:

1. Copia un test event code

   In TikTok Events Manager, apri il tuo pixel e vai su Test events. Copia il test event code.

2. Incollalo in ROASaurus

   Apri Tracking & platforms, modifica il pixel TikTok e incolla il codice nel campo Test event code. Gli eventi server ora lo portano.

3. Fai un ordine di prova

   Visita il tuo negozio, guarda un prodotto, aggiungilo al carrello e completa un ordine.

4. Controlla entrambi i lati

   In Test events, filtra per eventi del browser e del server. Dovresti vedere l’acquisto da entrambi. In ROASaurus, l’Event log mostra ogni invio del server come inviato o non riuscito.

5. Rimuovi il codice di test

   Elimina il test event code quando hai finito, così i tuoi eventi server reali non vengono più inviati come eventi di test.

TikTok può rispondere a una richiesta con HTTP 200 e rifiutare comunque l’evento, con un codice di errore nel corpo della risposta. ROASaurus legge quel codice, quindi un evento rifiutato compare come fallito nell’Event log invece di passare inosservato.

Dopo un giorno di traffico reale, apri la panoramica del pixel in Events Manager. Elenca ogni evento con il suo metodo di connessione, il punteggio Event Match Quality e quando è stato ricevuto l’ultima volta. I dettagli dell’evento includono informazioni su associazione e deduplicazione, e Diagnostics elenca i problemi di qualità con indicazioni su come risolverli.

Come configurare la TikTok Events API su Shopify con ROASaurus

Ti servono un negozio Shopify con l’app ROASaurus e l’accesso a TikTok Events Manager. La pagina dell’integrazione TikTok elenca ogni campo che ROASaurus invia.

1. Collega il tuo negozio Shopify

   Vai su Add a store › Shopify, clicca Install app e attiva l’app embed di ROASaurus nell’editor del tema. L’embed cattura ttclid e il cookie _ttp su ogni pagina. La guida alla configurazione di Shopify mostra ogni passaggio.

2. Aggiungi il pixel del checkout

   In Shopify admin › Settings › Customer events, aggiungi un pixel personalizzato chiamato ROASaurus e incolla lo snippet dalla tua pagina Tracking & platforms. Fa scattare il pixel TikTok al checkout, compresa la copia dell’acquisto dal browser.

3. Crea un access token

   In TikTok Events Manager, apri il tuo pixel e genera un access token della Events API nelle sue impostazioni. Copia il token e il codice del pixel.

4. Aggiungi il pixel TikTok in ROASaurus

   Vai su Tracking & platforms, clicca Add pixel sulla card TikTok e compila Pixel code e Events API access token. Lascia spuntato Also load the browser pixel (recommended, deduplicated), così gli eventi del browser e del server condividono gli id.

5. Aggiungi la spesa (facoltativo)

   Compila Advertiser ID for spend e un Marketing API token. ROASaurus importa quindi la spesa di TikTok, così le campagne TikTok mostrano ROAS e CPA accanto agli altri canali.

6. Testa, poi vai online

   Invia un ordine di prova con un test event code come descritto sopra, poi rimuovi il codice.

Con Respect visitor consent attivo, che è l’impostazione predefinita, ROASaurus segue la scelta dell’acquirente nel banner dei cookie di Shopify. Quando un acquirente rifiuta i cookie di marketing, ROASaurus non carica per lui il pixel TikTok, non imposta nessun visitor id, quindi i suoi clic non vengono collegati a lui, e non invia i suoi eventi di navigazione a TikTok. Il suo ordine pagato viene comunque inviato alla Events API dal server, con i dati dell’ordine con hash e l’indirizzo IP e lo user agent dell’ordine, ma senza ttclid né _ttp. La guida su consenso e privacy spiega cosa viene memorizzato e inviato.

Con la spesa sincronizzata, le campagne TikTok compaiono nei report di attribuzione accanto a Meta, e l’analisi delle creatività aggiunge le statistiche video di TikTok per annuncio. ROASaurus attribuisce gli ordini ai clic sugli annunci e agli UTM che ha registrato, e conta le conversioni view-through solo come stima modellata nel suo modello Clicks & views, quindi i suoi totali di solito differiscono da TikTok Ads Manager. Per le altre piattaforme server-side, vedi la guida alla Pinterest Conversions API e la guida alla Meta Conversions API.

Fonti

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

In ROASaurus

• Integrazione TikTok
• Tracciamento server-side in ROASaurus
• Assistenza: evita il doppio conteggio
• Assistenza: configura ROASaurus su Shopify

Continua a leggere