API Conversions

Configura l'API Conversions come piattaforma

Se offri la configurazione del pixel di Meta nell'ambito dei tuoi servizi di gestione dei tag, ti consigliamo di aggiungere le funzionalità dell'API Conversions. L'integrazione con l'API Conversions consente ai tuoi clienti di inviare eventi web direttamente a Facebook, senza dover fare affidamento sugli eventi del pixel del browser.

Eventi del server vs eventi del browser

Prima di iniziare, è importante comprendere la relazione tra gli eventi del server e il pixel di Meta. Gli eventi del server vengono inviati tramite l'API Conversions e usati nella misurazione, nei report e nell'ottimizzazione allo stesso modo degli eventi del pixel del browser.

Se inviare eventi del pixel del browser è come inviare posta via aria, inviare eventi del server è come inviare posta via terra. Sono entrambi meccanismi per trasportare il pacchetto (dati su un evento) a un indirizzo di destinazione (un ID pixel). Pertanto, ti consigliamo vivamente di creare l'integrazione dell'API Conversions sulla tua piattaforma come estensione dell'attuale offerta del pixel di Meta (anziché un plug-in o un servizio separati) per i seguenti motivi:

  • Gli eventi del server usano l'ID pixel come destinazione
  • Gli eventi del server vengono elaborati allo stesso modo degli eventi del pixel del browser una volta inviati a Facebook
  • La deduplicazione sarà più facile da implementare
  • Facilità d'uso per i clienti. Ad esempio, gli eventi del server possono essere inviati insieme agli eventi del browser, per impostazione predefinita.

Una volta integrata la tua piattaforma con l'API Conversions, ti consigliamo di inviare gli stessi eventi web tramite browser e server. Questa ridondanza aiuta a garantire l'affidabilità del segnale. Gli eventi che in precedenza avrebbero potuto essere persi sul lato browser, per una serie di motivi di rete, sono ora catturati tramite l'API Conversions.

Per inviare eventi tramite browser e server, devi impostare correttamente lo stesso event_id per gli eventi corrispondenti. Questo consente a Facebook di deduplicare correttamente i tuoi eventi.

Prerequisiti

  1. Una piattaforma web in grado di condividere eventi su Facebook. Ad esempio, strumento di creazione di siti web, strumento di gestione dei tag o piattaforma AdTech.
  2. Comunicazione appropriata agli utenti e relativo consenso per la condivisione dei dati degli eventi con Facebook, come richiesto dalle Condizioni per gli strumenti business di Facebook.
  3. Un rappresentante di Facebook
  4. I prerequisiti per l'integrazione dell'API Conversions standard:

Per iniziare a offrire l'API Conversions come piattaforma, la tua app deve essere sottoposta ad Analisi dell'app. Durante tale processo, devi richiedere i livelli di accesso, le funzionalità e le autorizzazioni seguenti:

Primi passi

Se è la prima volta che usi l'API Conversions, segui questi passaggi per creare un Business Manager, un'app di Meta, un pixel di Meta e un utente di sistema. Potrai quindi usare il token d'accesso dell'utente di sistema per inviare eventi del server tramite l'API Conversions.

Passaggio 1: Crea un Business Manager.

Passaggio 2: Crea un'app Meta sotto il Business Manager appena creato.

Passaggio 3: crea un pixel di Meta sotto il Business Manager appena creato:

Passaggio 4: Genera un token d'accesso dell'utente di sistema.

Passaggio 5: Invia un evento del server al tuo pixel di Meta.

Invia eventi per conto dei clienti

Dopo aver inviato correttamente un evento del server al tuo pixel di Meta, hai delle opzioni su come inviare eventi per conto dei tuoi clienti.

Per i pixel di Meta di proprietà o gestiti dal Business Manager del partner

  1. In Business Manager, vai alla sezione Utenti e seleziona la tab Utente di sistema. Clicca sull'utente di sistema specifico che stai usando per l'API Conversions.
  2. Vai alla finestra di dialogo Assegna risorsa e scegli Pixel. Quindi, seleziona i pixel per conto dei quali vuoi inviare gli eventi.
  3. Per ogni pixel, seleziona l'autorizzazione Gestisci pixel e clicca su Salva modifiche.
  4. Torna alla pagina dei dettagli dell'utente di sistema. Verifica che i pixel selezionati siano visibili lì.

Per i pixel di Facebook non gestiti dal partner

Devi prima richiedere l'autorizzazione per inviare eventi per conto dei tuoi clienti. Hai a disposizione le opzioni di autenticazione riportate sotto.

Estensione Facebook Business (consigliata)

Con questa opzione, l'estensione Facebook Business (FBE) restituisce tutte le informazioni necessarie per inviare eventi per conto del cliente tramite la procedura seguente. FBE fornisce un endpoint per recuperare i token d'accesso dell'utente di sistema creati nel Business Manager del cliente. La procedura include le autorizzazioni per inviare eventi del server e avviene in maniera automatica e sicura.

L'endpoint richiede un token d'accesso utente come parametro di input. I nuovi utenti FBE devono chiamare questo endpoint per recuperare il token d'accesso dell'utente di sistema dopo aver completato la configurazione dell'estensione Facebook Business Gli utenti esistenti devono richiedere una nuova autenticazione prima di chiamare il nuovo endpoint dell'API.

Token d'accesso dell'utente di sistema del cliente

Con questa opzione, devi far creare manualmente al tuo cliente un token d'accesso dell'utente di sistema tramite l'API Conversions all'interno delle Impostazioni del pixel. Puoi quindi inviare eventi al pixel dell'inserzionista con quel token.

Un utente di sistema o un utente di sistema con funzioni avanzate deve installare l'app che sarà usata per generare il token d'accesso. Con questa configurazione, all'app è consentito effettuare chiamate all'API per conto dell'utente di sistema o dell'utente di sistema con funzioni avanzate.

Segui la nostra documentazione Primi passi e richiedi un token dell'utente di sistema al tuo inserzionista. Ricorda di usare per il test il tuo pixel di Meta e il tuo token d'accesso.

Condivisione da parte del cliente di un pixel di Meta su un Business Manager del partner

Con questa opzione, il cliente condivide il suo pixel di Meta con il partner tramite le impostazioni di Business Manager o tramite l'API. Quindi, puoi assegnare l'utente di sistema del partner al pixel del cliente e generare un token d'accesso per inviare eventi del server.

Attribuisci gli eventi alla tua piattaforma usando il campo partner_agent.

Per attribuire gli eventi dell'API Conversions alla tua piattaforma, usa il campo partner_agent. In questo modo, imposti l'identificativo della piattaforma quando invii eventi per conto di un cliente. Collabora con il tuo rappresentante di Facebook per concordare un identificativo per la tua piattaforma. Invialo quindi con ogni evento del server.

Esempio di payload dell'evento

Se l'identificativo della piattaforma è datapartner, si tratta di un esempio di payload di un evento di acquisto inviato per conto del tuo cliente:

    
{
  "data": [
    {
      "user_data": {
        "em": "8159ea0e33c51a774b83104ee562784f9b1836c852102046e4bd8385706fe7ca"
      },
      "event_name": "PageView",
      "event_time": 1579645238
    },
    {
      "user_data": {
        "em": "8159ea0e33c51a774b83104ee562784f9b1836c852102046e4bd8385706fe7ca"
      },
      "custom_data": {
        "currency": "USD",
        "value": "50"
      },
      "event_name": "Purchase",
      "event_time": 1579645238
    }
  ],
  "partner_agent": "datapartner"
}

Domande frequenti

Sending events sent via the Conversions API is just like sending events via Facebook Pixel. The only difference is that the event is sent via the server, instead of the browser. So, why make an effort to integrate with the Conversions API? Here are some important use cases:

Capture offline and down-funnel events

If someone uses an advertisers’ website to sign up for a credit card, they can send events such as ViewContent, Application Start, and Application Submit via the browser to the Facebook Pixel. However, the end user still needs to be approved for this credit card. The Approval event happens offline and cannot be sent via browser. To register this final step, the advertiser can send the Approval via the Conversions API.

Signal resiliency

Browser side events can be lost for many reasons:

  • The user might navigate away before the page has finished loading.
  • Ad blockers could prevent the event from firing.
  • The changing internet landscape might change the way inter-domain messages are sent.

These examples can all be mitigated by sending events via the Conversions API.

Sensitive data

Many advertisers have expressed concerns about sharing data via the browser when that data could be seen or inspected. This can be mitigated by sending data via the Conversions API.

For example, advertisers may want to send data like profit margin or lifetime value (LTV) along with a purchase event. This way, ads can be optimized towards a specific type of customer.

Permalink

Since browser events are always vulnerable to obstacles, we recommend that you only send events collected from the Conversions API sources. For example, if:

  • One of the ways your customer ingests data into your platform is via a browser JavaScript tag, or
  • You send that data to Facebook via the Conversions API

the data is open to the browser-side risks.

To take full advantage of the Conversions API, no part of the data flow should be reliant on the browser.

Permalink

We recommend that you provide advertisers with a way to test this connection on your own platform.

  1. Send a test event via the Conversions API to the advertiser’s pixel. Look for a 200 return code.
  2. Update the status of the connection appropriately.
Permalink

Facebook tries to deduplicate identical events sent through the Facebook Pixel and the Conversions API. We determine if events are identical based on their event_id and event_name. For more information, see Handling Duplicate Pixel and Conversions API Events.

Permalink

The external_id parameter is a string that represents a user on an advertiser's system. These IDs help improve ads attribution and create audiences.

You can send external_ids via browser or the Conversions API, but you must be consistent across channels. For example, if you send a browser pixel event with external_id set to 123, your server event for that same user should also have external_id set to 123.

Permalink