Dopo aver completato i prerequisiti nella pagina Primi passi, usa questa pagina per scoprire come inviare eventi e usare lo strumento Testa gli eventi. Dopo aver inviato un evento, verifica la configurazione.
L'API Conversions si basa sull'API Marketing di Facebook, realizzata partendo dalla nostra API Graph. Le API Marketing e Graph hanno programmi di obsolescenza delle versioni diversi. Il ciclo di rilascio è allineato con l'API Graph, quindi ogni versione è supportata per almeno due anni. Questa eccezione è valida solo per l'API Conversions.
API Conversions: panoramicaParametriGli eventi web, nell'app e del punto vendita fisico condivisi usando l'API Conversions richiedono parametri specifici. Usando l'API Conversions, dichiari che il parametro action_source
, per quel che ne sai, è accurato. La lista di parametri richiesti è disponibile qui.
Per inviare nuovi eventi, effettua una richiesta POST
al segmento /events
di questa API da questo percorso: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
. Quando esegui un POST su questo segmento, Facebook crea nuovi eventi server.
curl -X POST \
-F 'data=[
{
"event_name": "Purchase",
"event_time": 1734847102,
"user_data": {
"em": [
"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
],
"ph": [
"254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
"6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
],
"client_ip_address": "123.123.123.123",
"client_user_agent": "$CLIENT_USER_AGENT",
"fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
"fbp": "fb.1.1558571054389.1098115397"
},
"custom_data": {
"currency": "usd",
"value": 123.45,
"contents": [
{
"id": "product123",
"quantity": 1,
"delivery_category": "home_delivery"
}
]
},
"event_source_url": "http://jaspers-market.com/product/123",
"action_source": "website"
}
]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<PIXEL_ID>/events
Allega il token d'accesso sicuro generato usando il parametro di query access_token
alla richiesta. Puoi anche usare il Tool di esplorazione per la API Graph per eseguire una richiesta POST
all'endpoint /<pixel_id>/events
.
Di seguito è riportato un esempio del corpo della richiesta:
{ "data": [ { "event_name": "Purchase", "event_time": 1633552688, "event_id": "event.id.123", "event_source_url": "http:\/\/jaspers-market.com\/product\/123", "action_source": "website", "user_data": { "client_ip_address": "192.19.9.9", "client_user_agent": "test ua", "em": [ "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" ], "ph": [ "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4", "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6" ], "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890", "fbp": "fb.1.1558571054389.1098115397" }, "custom_data": { "value": 100.2, "currency": "USD", "content_ids": [ "product.id.123" ], "content_type": "product" }, "opt_out": false }, { "event_name": "Purchase", "event_time": 1633552688, "user_data": { "client_ip_address": "192.88.9.9", "client_user_agent": "test ua2" }, "custom_data": { "value": 50.5, "currency": "USD" }, "opt_out": false } ] }
event_time
indica data e ora della transazione relativa all'evento. Dovrebbe essere inviato come un'indicazione temporale Unix in secondi che indica quando si è verificato l'evento effettivo. La data e l'ora specificate possono essere precedenti a quelle di invio dell'evento a Facebook. Questo rende possibile l'elaborazione di gruppo e l'ottimizzazione delle prestazioni del server.
event_time
può essere fino a 7 giorni prima dell'invio di un evento a Facebook. 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 del punto vendita fisico con physical_store
come action_source
, devi caricare le transazioni entro 62 giorni dalla conversazione.
Usando l'API Conversions, dichiari che il parametro action_source
, per quel che ne sai, è accurato.
Puoi inviare fino a 1000 eventi in data
. Tuttavia, per prestazioni ottimali, ti consigliamo di inviare gli eventi non appena si verificano e idealmente entro un'ora. Se un evento inviato in un batch non è valido, viene rifiutato l'intero batch.
Consulta la pagina dei parametri delle informazioni dei clienti per vedere quali parametri devono essere sottoposti ad algoritmo di hashing prima di essere inviati a Facebook. Se utilizzi uno dei nostri SDK Business, l'hashing viene applicato direttamente dall'SDK.
Scopri di più su tre funzioni specifiche dell'SDK Business progettate appositamente per gli utenti dell'API Conversions: Richieste asincrone, Creazione di batch simultanea e Interfaccia servizi HTTP. Versione minima del linguaggio necessaria per usare queste funzioni:
Il supporto dell'SDK Business per PHP 5 è stato dichiarato obsoleto da gennaio 2019. Effettua l'aggiornamento a PHP 7 per usare l'SDK Business.
Se devi usare PHP 5, considera di utilizzare l'implementazione Swagger.
Dopo aver inviato gli eventi, verifica che siano stati correttamente ricevuti in Gestione eventi:
PIXEL_ID
nella tua richiesta POST
. Per maggiori informazioni, consulta Centro assistenza per le aziende: navigazione in Gestione eventi.Puoi verificare che gli eventi del tuo server vengano ricevuti correttamente da Facebook utilizzando la funzione Testa gli eventi in Gestione eventi. Per individuare lo strumento, vai a Events Manager > Data Sources > Your Pixel > Test Events
.
Lo strumento Testa gli eventi genera un ID di test. Invia l'ID di test come parametro test_event_code
per iniziare a vedere comparire l'attività degli eventi nella finestra Testa gli eventi.
Nota: il campo test_event_code
deve essere utilizzato solo per i test. Devi rimuoverlo quando invii il payload di produzione.
Gli eventi inviati con test_event_code
non vengono ignorati. Confluiscono in Gestione eventi e vengono utilizzati per scopi di targetizzazione e misurazione delle inserzioni.
Ecco un esempio di come dovrebbe essere strutturata la richiesta:
Ecco un esempio di come appare la richiesta nel Tool di esplorazione per la API Graph:
Puoi generare questo payload di prova usando lo strumento di assistenza per il payload. Tieni presente che il codice dell'evento di prova è solo per testare il payload.
Gli eventi del server vengono visualizzati nella finestra Testa gli eventi dopo aver inviato la richiesta.
Per queste due API, implementa le opzioni di elaborazione dei dati aggiungendo data_processing_options
, data_processing_options_country
e data_processing_options_state
all'interno di ogni evento nel parametro dei dati dei tuoi eventi.
Nota: le API App Events e Offline Conversions non sono più consigliate per le nuove integrazioni. Al loro posto, ti consigliamo di usare l'API Conversions in quanto ora supporta gli eventi web, app e offline. Consulta API Conversions per App Events e API Conversions per Offline Events per maggiori informazioni.
Per indicare esplicitamente la non abilitazione dell'Utilizzo limitato dei dati (LDU), specifica un array vuoto per ogni evento o semplicemente rimuovi il campo nel payload:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": [] } ] }
Per abilitare la funzione di LDU e richiedere a Meta di individuare la posizione geografica:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>", "client_ip_address": "256.256.256.256" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 0, "data_processing_options_state": 0 } ] }
Per abilitare la funzione di LDU e specificare manualmente la posizione, ad esempio per la California:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 1, "data_processing_options_state": 1000 } ] }
L'API Offline Conversions ti consente di caricare manualmente gli eventi da un file .csv
. In questo caso, aggiungi Opzioni trattamento dati, Paese trattamento dati e provincia/stato trattamento dati come colonne all'interno del file. Ulteriori informazioni sono disponibili nell'interfaccia utente per il caricamento manuale.
Scopri di più sulle opzioni di elaborazione dei dati.
L'API Marketing dispone della propria logica per il rate limiting ed è esclusa da tutti i rate limiting dell'API Graph. Di conseguenza, se effettui una chiamata API Marketing, questa non viene calcolata nel throttling dell'API Graph.
Non esiste un rate limiting specifico per l'API Conversions. Le chiamate API Conversions sono contate come chiamate API Marketing. L'unica limitazione è che puoi inviare fino a 1000 eventi alla volta. Vedi Inviare richieste per maggiori informazioni.
Rate limiting dell'API MarketingQuesta guida descrive le funzioni avanzate dell'SDK di Meta Business progettate appositamente per gli utenti del gateway dell'API Conversions. Per l'uso di base del gateway dell'API Conversions, consulta la relativa documentazione.
Prima di usare una delle funzioni elencate di seguito, devi aver installato l'SDK di Meta Business. Consulta Primi passi con l'SDK di Meta Business o segui le istruzioni README riportate di seguito:
Attualmente, queste funzioni sono disponibili solo sull'SDK Business PHP e Java. Gli altri linguaggi saranno implementati entro la fine del 2023.
Versione minima del linguaggio necessaria per usare queste funzioni:
PHP: 7.2 o successiva
Java: 8 o successiva
Nota: per deduplicare gli eventi sull'endpoint dell'API Conversions, passa l'eventId
nella tua richiesta. In questo modo eviterai che vengano mostrati gli eventi duplicati se è abilitata la pubblicazione dell'API Conversions.
CAPIGatewayIngressRequest
Parametro | Descrizione |
---|---|
endpointUrl stringa | L'endpoint del gateway dell'API Conversions a cui vengono inviati gli eventi. Oltre a verificare la validità dell'URL, non saranno effettuate altre prevalidazioni sul parametro. Esempio: https://test.example.com |
accessKey stringa | Chiave di accesso del gateway dell'API Conversions necessaria per inviare eventi all'endpoint degli eventi del gateway dell'API Conversions. Queste sono le istruzioni per generarla. |
CAPIGatewayIngressRequest
Parametro | Descrizione |
---|---|
setSendToDestinationOnly Booleano | Flag booleano che indica se gli eventi vengono inviati solo all'endpoint selezionato. Impostazione predefinita: |
setFilter Funzione CustomEndpointRequest.Filter() | Funzione di filtro che elabora ogni evento. Se la logica di filtro restituisce il valore true, l'evento viene passato. In caso contrario, viene ignorato. Devi implementare la funzione shouldSendEvent nell'interfaccia che ha il parametro Event. Impostazione predefinita: |
Per i sistemi che utilizzano già l'SDK Business, basta fare riferimento alla nuova CAPIGatewayIngressRequest e aggiungerla all'oggetto customEndpoint di eventRequest.
// this is the standard event request that we attach events to $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); // pass the events to this event Request object $event_request->setEvents($events); $event_request->execute()
Per i sistemi che utilizzano già l'SDK Business, basta fare riferimento alla nuova CAPIGatewayIngressRequest e aggiungerla all'oggetto customEndpoint di eventRequest.
// this is the standard event request that we attach events to EventRequest eventRequest = new EventRequest(PIXEL_ID, context); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $user_data = (new UserData()) ->setEmails(array('joe@eg.com')) ->setPhones(array('12345678901', '14251234567')) ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') ->setFbp('fb.1.1558571054389.1098115397'); $event1 = (new Event()) ->setEventName('Purchase') ->setEventId('125') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123') ->setUserData($user_data); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute(); print($response->__toString());
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventId("125").eventName("Purchase") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequestAsync($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $capiIngressRequest->setSendToDestinationOnly(true); $event_request->setCustomEndpoint($capiIngressRequest); $event1 = (new Event()) ->setEventName('test Async Event') ->setEventId('134423232') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123'); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute()->wait();
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); capiSyncRequest.setSendToDestinationOnly(true); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventName("test Async Event") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11222") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.executeAsync();
lass APIFilter implements Filter { public function shouldSendEvent(Event $event): bool { if ($event->getEventId() === '125') { return false; } return true; } } $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $capiIngressRequest->setFilter(new APIFilter());
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() { @Override public boolean shouldSendEvent(Event event) { if (event.getEventId().equals("125")) { return true; } return false; } });