Pinterest Conversions API per Shopify: guida alla configurazione

La Pinterest Conversions API è il modo di Pinterest per inviare eventi di conversione da server a server. Il tuo negozio, o uno strumento come ROASaurus, invia eventi come gli acquisti direttamente al tuo account pubblicitario Pinterest, invece di affidarsi solo al Pinterest Tag nel browser dell’acquirente. Pinterest usa i dati per i report sulle conversioni, l’ottimizzazione delle campagne e il targeting.

Questa guida tratta la v5 dell’API e gli eventi che accetta, il click id epik, come vengono sottoposti ad hash i dati dei clienti, come funziona la deduplicazione con il Pinterest Tag, come testare e come configurare tutto su Shopify.

Che cos’è la Pinterest Conversions API?

Il Pinterest Tag è uno script nel browser dell’acquirente. La Conversions API fa lo stesso lavoro da un server. Nella versione 5 dell’API invii gli eventi all’endpoint degli eventi del tuo account pubblicitario, autorizzato da un conversion access token che crei in Pinterest Ads Manager. Ogni evento dice dove è avvenuto: per un negozio online, l’action source è web.

Pinterest chiede agli inserzionisti che usano anche il Tag di evitare di contare una conversione due volte, passando un event_id con ogni evento. Chiede anche gli eventi in tempo reale, o al massimo un’ora dopo che sono avvenuti.

Su Shopify, una connessione server ha un vantaggio chiaro: gli acquisti arrivano dall’ordine stesso. Shopify segnala ogni ordine pagato a ROASaurus tramite webhook, e ROASaurus lo invia a Pinterest poco dopo il pagamento, a prescindere dal fatto che il Tag sia scattato nel browser. La guida al tracciamento server-side su Shopify spiega l’idea più a fondo.

Quali eventi accetta la Pinterest Conversions API?

Pinterest ha un elenco fisso di nomi di eventi standard, scritti in minuscolo con i trattini bassi, come page_visit, add_to_cart e checkout. Puoi anche definire fino a 15 tipi di evento personalizzati per inserzionista. ROASaurus mappa i cinque eventi di shopping di Shopify in questo modo:

Il nome può creare confusione. Il checkout di Pinterest è l’acquisto concluso, non l’inizio del checkout. L’inizio del checkout è un evento separato, initiate_checkout.

Per l’evento di checkout, Pinterest consiglia di inviare il valore, la valuta, l’order id, gli ID contenuto e il numero di articoli. ROASaurus li invia tutti e cinque, più la quantità e il prezzo di ogni articolo. Pinterest chiede il valore al netto di imposte e spedizione. Su Shopify, ROASaurus invia esattamente quello: il totale dell’ordine meno imposte e spedizione, dal server e dal tag del browser. Quando la piattaforma del negozio online non riporta separatamente imposte e spedizione, ROASaurus invia il totale dell’ordine.

Come fa Pinterest ad associare un evento a una persona?

Ogni evento porta dati dell’utente. Pinterest richiede almeno una di tre cose: un indirizzo email con hash, un id pubblicitario mobile con hash, oppure l’indirizzo IP insieme allo user agent. Un negozio online non ha un id pubblicitario, quindi gli servono l’email oppure l’indirizzo IP e lo user agent. ROASaurus salta un evento privo di entrambe le opzioni, invece di inviarne uno che Pinterest non può usare.

Il click id epik

Il click id di Pinterest può arrivare da due posti: un parametro epik nell’URL della pagina di atterraggio, oppure il cookie _epik sul tuo dominio. La guida all’API di Pinterest consiglia di passare il valore del cookie _epik, perché funziona anche quando il parametro dell’URL manca o è stato rimosso, il che dà una copertura migliore.

ROASaurus legge entrambi sul tuo negozio, usando il parametro dell’URL quando un nuovo clic ne porta uno e il cookie in caso contrario. Salva il click id insieme al visitatore e lo invia nel campo click_id di ogni evento server, acquisto compreso. Le visite con un epik contano come visite Pinterest nei report di attribuzione di ROASaurus.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Come funziona la deduplicazione con il Pinterest Tag?

Se il Tag e l’API segnalano entrambi un acquisto, Pinterest riceve due eventi per un solo ordine. Per trattarli come uno, serve lo stesso id da entrambe le parti: l’event id nel Tag deve corrispondere all’event_id nell’evento server. Pinterest tiene il primo evento che riceve e rimuove i duplicati che arrivano entro 48 ore.

ROASaurus costruisce il purchase id dall’id dell’ordine Shopify. L’acquisto dell’ordine 5512345678901 ha l’event id order-5512345678901, sia nel Tag che scatta al checkout sia nell’evento server.

Tutti e cinque gli eventi vengono deduplicati

Ogni evento di shopping in ROASaurus ha un solo event id, usato dal Tag nel browser e dall’evento server. Il Tag usa i nomi propri di Pinterest per gli stessi eventi: pagevisit, viewcontent, addtocart, initiatecheckout e checkout, che corrispondono a page_visit, view_content, add_to_cart, initiate_checkout e checkout nell’API. Quindi, quando entrambi sono attivi, Pinterest tiene una sola copia di ogni visita alla pagina, visualizzazione di prodotto, aggiunta al carrello, avvio del checkout e acquisto.

Puoi usarla in due modi:

• Tag e Conversions API insieme. Il Tag aggiunge i segnali del browser, il server colma ciò che il Tag perde e Pinterest unisce le copie.
• Usa l’API senza il Tag. Lascia vuoto il Tag ID o disattiva Also load the browser tag. Ogni evento viene allora inviato una sola volta, solo dal server.

L’articolo di aiuto sul doppio conteggio tratta gli stessi controlli per le altre piattaforme pubblicitarie.

Come testare la Pinterest Conversions API?

L’API ha un flag di test. Le richieste inviate con test=true vanno in una sandbox: Pinterest le tratta come dati di test e non le usa per i report né per l’ottimizzazione.

1. Attiva la modalità di test

   In ROASaurus, modifica il pixel Pinterest in Tracking & platforms e spunta Test mode (events show under Test events, max 20). Ogni evento server viene allora inviato con test=true. Pinterest elabora al massimo 20 eventi di test per batch.

2. Fai un ordine di prova

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

3. Leggi il risultato

   Apri l’Event log. Pinterest può rispondere HTTP 200 anche se un evento in una richiesta è fallito, quindi ROASaurus controlla lo stato di ogni evento e mostra lì gli errori.

4. Disattiva la modalità di test

   Deseleziona la modalità di test, così gli eventi contano nei report e nell’ottimizzazione.

5. Controlla Events Overview

   In Pinterest Ads Manager, apri la pagina Events Overview. Mostra gli eventi che arrivano e le conversioni deduplicate. Pinterest consiglia di puntare a un Event Quality Score Good.

Come configurare la Pinterest Conversions API su Shopify con ROASaurus

Ti servono un negozio Shopify con l’app ROASaurus e l’accesso a Pinterest Ads Manager. La pagina dell’integrazione Pinterest 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. Cattura epik e il cookie _epik su ogni pagina. La guida alla configurazione di Shopify mostra ogni passaggio.

2. Crea un conversion access token

   In Pinterest Ads Manager, vai su Conversions e crea un conversion access token. Annota l’ID del tuo account pubblicitario.

3. Aggiungi il pixel Pinterest in ROASaurus

   Vai su Tracking & platforms, clicca Add pixel sulla card Pinterest e compila Ad account ID e Conversion access token.

4. Aggiungi il tuo Tag ID

   Per la deduplicazione con il Tag, compila Pinterest Tag ID e lascia spuntato Also load the browser tag. Senza un Tag ID, ROASaurus invia solo eventi server e non carica il Tag.

5. 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 l’evento checkout del Tag nel checkout di Shopify, con l’order id come event_id.

6. Scegli gli eventi server, poi testa

   Scegli gli eventi server che vuoi e testa con la modalità di test prima di andare online.

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 Pinterest Tag, non imposta nessun visitor id, quindi i suoi clic non vengono collegati a lui, e non invia i suoi eventi di navigazione a Pinterest. Il suo ordine pagato viene comunque inviato alla Conversions API dal server, con i dati dell’ordine con hash e l’indirizzo IP e lo user agent dell’ordine, ma senza click id. La guida su consenso e privacy spiega cosa viene memorizzato e inviato.

Collega il tuo account pubblicitario Pinterest in Setup › Ad spend e ROASaurus importa la spesa delle campagne ogni ora, così vedi il ROAS di Pinterest e il profitto dopo gli annunci nell’analisi del profitto. La guida alla TikTok Events API tratta la stessa configurazione per TikTok, dove ogni evento che viaggia in entrambe le direzioni viene deduplicato.

Fonti

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

In ROASaurus

• Integrazione Pinterest
• Tracciamento server-side in ROASaurus
• Assistenza: evita il doppio conteggio

Continua a leggere