Invio di eventi offline usando l'API Conversions

L'API Conversions è il metodo di integrazione consigliato da Meta per inviare eventi offline e in punti vendita fisici a Meta per essere usati nella misurazione, nell'attribuzione e nella targetizzazione delle inserzioni. Questa pagina descrive come inviare eventi offline tramite un'integrazione diretta o di partner dell'API Conversions.

Prerequisiti

Dataset

Gli eventi offline inviati tramite l'API Conversions devono essere associati a un dataset.

Puoi fare la chiamata GET a https://graph.facebook.com /v16.0/{ads-pixel-id}/? fields=is_consolidated_container per rilevare se il dataset dell'inserzionista è consolidato e quindi idoneo per passare eventi offline usando l'API Conversions.

Autorizzazioni

• Per implementare un'integrazione diretta come inserzionista, segui le istruzioni riportate qui per prerequisiti e autorizzazioni.

• Per implementare un'integrazione della piattaforma partner, segui le istruzioni riportate qui per prerequisiti e autorizzazioni.

Configurazione

1. Configurazione dei parametri degli eventi offline

Gli inserzionisti possono usare la configurazione menzionata qui e fare riferimento all'insieme attuale di parametri che è possibile inviare tramite l'API Conversions. Per l'invio di eventi offline e nei punti vendita, nel payload è possibile condividere i seguenti campi possono essere condivisi nel payload:

• Gli inserzionisti devono inviare action_source come physical_store per tutti gli eventi offline e nei punti vendita. Questo parametro è obbligatorio per tutti i tipi di eventi del server. Usando l'API Conversions, dichiari che il parametro action_source, per quel che ne sai, è accurato.
• Tutti i campi degli eventi del server obbligatori per l'API Conversions devono essere rispettati.
• Parametri delle informazioni dei clienti (vedi sotto per l'elenco appropriato dei parametri per gli eventi offline e nei punti vendita).
• Parametri dei dati personalizzati (vedi sotto per l'elenco appropriato dei parametri per gli eventi offline e nei punti vendita).
• Parametro opzionale: il parametro upload_tag è ancora supportato per i caricamenti di eventi offline per gli inserzionisti che usano l'API legacy per gli eventi offline.

Parametri delle informazioni dei clienti

La lista seguente contiene i parametri delle informazioni dei clienti che sono tipicamente usati per eventi offline e nei punti vendita:

Parametri dei dati personalizzati

La seguente sezione contiene parametri personalizzati comuni usati dagli eventi offline e nei punti vendita. Per altri campi di dati personalizzati, consulta la lista completa accettata per l'API Conversions al seguente link.

2. Invio di eventi

Per inviare nuovi eventi, fai una richiesta POST all'API Conversions da questo percorso: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

Quando pubblichi su questo segmento, Meta crea nuovi eventi offline e nel punto vendita. Per maggiori dettagli, consulta il seguente documento per gli sviluppatori.

Di seguito è riportata una panoramica di come si inseriscono i parametri nello schema complessivo del payload:

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

Ti consigliamo di caricare in tempo reale o su base giornaliera per ottenere risultati di ottimizzazione ottimali, in modo che i dati offline possano essere associati efficacemente alle prestazioni delle inserzioni che stai pubblicando.

event_time può essere fino a 7 giorni prima dell'invio di un evento a Meta. Se un qualsiasi event_time in data è relativo a più di 7 giorni, restituiamo un errore per l'intera richiesta e non elaboriamo alcun evento. Per gli eventi offline e nei punti vendita fisici con physical_store come action_source, devi caricare le transazioni entro 62 giorni dalla conversazione.

I dati che carichi vengono elaborati in tempo reale, quindi di solito puoi visualizzare i risultati non appena li aggiungi. Puoi fare riferimento al documento del Centro assistenza relativo alle best practice per i dati degli eventi offline.

3. Configurazione della deduplicazione

A differenza della configurazione della deduplicazione negli eventi dell'API Conversions e del pixel di Meta, gli eventi offline possono essere deduplicati solo rispetto ad altri eventi offline. Sono supportati due metodi di deduplicazione: basata su order_id o basata su user. La deduplicazione utilizza la combinazione di campi: dataset_id, event_time, event_name, item_number e il campo chiave basato sul metodo nel payload dell'evento dato.

La deduplicazione predefinita usa order_id con una combinazione dei campi precedenti. Se order_id non è presente nel payload, viene usata la logica di deduplicazione basata su utente.

Ad esempio, se ci sono due ordini con event_time identici e event_name ha lo stesso order_id o lo stesso insieme di parametri delle informazioni dei clienti senza order_id, questi verranno considerati duplicati e verrà preso il primo evento. Il metodo di deduplicazione basato su user funziona solo con gli stessi campi dei parametri delle informazioni dei clienti nei due payload.

La finestra massima di deduplicazione è di 7 giorni.

4. Risoluzione dei problemi degli eventi

Puoi usare lo Strumento di assistenza per il payload per generare dati del payload:

• Quando applicabile, scegli physical_store come origine delle azioni. Usando l'API Conversions, dichiari che il parametro action_source, per quel che ne sai, è accurato.
• Compila le informazioni per gli eventi che verranno inviati a Meta
• Questo genererà il payload dell'evento, che può essere usato come modello per l'integrazione dell'API Conversions

Usa lo strumento Testa gli eventi in Gestione eventi per i test. Tieni presente che lo strumento Testa gli eventi supporta solo eventi web e nell'app.

Altri contenuti da consultare

• Panoramica dell'API Conversions
• Utilizzo dell'API Conversions
• Parametri dell'API Conversions
• Best practice

Articoli del Centro assistenza per le aziende

• Creare un dataset durante la creazione dell'insieme di eventi offline
• Best practice per i dati degli eventi offline
• Come gli inserzionisti possono usare le conversioni offline
• Come visualizzare i risultati delle campagne assegnate a un dataset specifico
• Come funziona la deduplicazione degli eventi per gli eventi offline