Implementazione end-to-end dell'API Conversions

L'API Conversions aiuta gli inserzionisti a fornire ai consumatori una trasparenza e un controllo dei dati adeguati e a continuare al tempo stesso a offrire esperienze personali. L'API consente di condividere dati direttamente dal tuo server, anziché tramite un browser.

Vantaggi dell'integrazione

• Visibilità del funnel più in profondità: l'API Conversions ti consente di condividere una serie di dati più ampia rispetto al pixel di Meta. Con l'API, puoi prendere decisioni tenendo conto di più informazioni, ad esempio dati CRM, eventi nella fase avanzata del funnel (tra cui i contatti qualificati) e percorsi di conversione multisito in un sito web e un luogo fisico.

• Controllo dei dati: se usata attraverso un'implementazione solo su server (ad esempio, senza il pixel di Meta), l'API Conversions ti offre un controllo maggiore sui dati che condividi. Puoi scegliere di aggiungere dati statistici agli eventi, fornendo dati come margini sui prodotti o informazioni passate, ad esempio i punteggi relativi al valore dei clienti.

• Affidabilità e resilienza dei segnali: la condivisione di dati tramite l'API Conversions potrebbe essere più affidabile rispetto ai soli metodi basati sul browser, come il pixel di Meta. L'API è progettata per essere meno soggetta a problemi come arresti anomali del browser o problemi di connettività. Le nuove restrizioni sulla trasmissione dei dati del settore potrebbero limitare l'efficacia dei cookie e del monitoraggio del pixel, quindi l'API Conversions ti aiuta a controllare i segnali relativi alle condivisioni che potrebbero non essere più registrati dal pixel.

Panoramica

L'integrazione dell'API Conversions prevede sostanzialmente due fasi principali:

• Preparazione: seleziona quale tipo di integrazione fa al caso tuo, definisci quali eventi inviare e controlla le opzioni di ottimizzazione disponibili.

• Esecuzione: scopri come implementare l'API. Per questa fase, puoi usare anche un'integrazione di partner.

Ecco una panoramica di tutta la procedura di integrazione:

Utenti esistenti del pixel

Se hai un'integrazione del pixel di Meta esistente, l'integrazione dell'API Conversions deve essere effettuata come estensione dell'integrazione del pixel, non come una connessione del tutto diversa.

Consenso generale

Se hai adottato una logica per controllare il consenso rispetto alla condivisione dei dati del pixel, usala anche per la condivisione dei dati tramite l'API Conversions.

Alternative

• Se vuoi ottimizzare le inserzioni per gli eventi nell'app, usa l'API App Events.

Preparazione

Scegli il tipo di integrazione

Innanzitutto, seleziona il tipo di integrazione che vuoi implementare:

Definisci gli eventi da inviare

Una volta scelto il metodo di integrazione, puoi definire quali eventi vuoi inviare. I segnali sono più utili se si trovano corrispondenze con gli ID utente di Meta, quindi è importante riflettere su quali parametri invii con un evento e sulla frequenza con la quale vuoi inviarli.

Opzioni per gli eventi

Invia gli eventi più pertinenti per la tua azienda. Consulta la lista completa degli eventi standard e personalizzati di Meta.

Parametri degli eventi

Puoi inviare più parametri per ogni evento. Consulta i parametri usati dall'API Conversions per scoprire di più su questi campi.

Puoi aggiungere più tipi di ID agli eventi, tra cui event_id, external_id e order_id. È importante conoscere le differenze tra questi parametri:

Aggiornamento dei dati

Ti consigliamo di inviare gli eventi in tempo reale o in batch in base a una specifica sequenza temporale tramite l'API Conversions. L'invio degli eventi in tempo reale o entro un'ora garantisce la possibilità di usarli per l'attribuzione e ottimizzarli per la pubblicazione delle inserzioni.

L'invio degli eventi più di due ore dopo che si sono verificati può comportare una riduzione significativa delle prestazioni per le inserzioni ottimizzate per questi eventi. Gli eventi inviati con un ritardo di 24 o più ore potrebbero subire problemi significativi in termini di attribuzione e pubblicazione ottimizzata delle inserzioni.

Se invii eventi con finestre di conversione lunghe, invia l'evento quanto più possibile in tempo reale dal momento nel quale viene completata la conversione.

Procedi con il prossimo passaggio dopo aver preparato:

• Una lista degli eventi da inviare
• I campi specifici che vuoi inviare per ogni evento
• La definizione della frequenza con la quale invierai gli eventi

Tipi di ottimizzazione disponibili

L'API Conversions offre i seguenti tipi di ottimizzazione:

Esecuzione

Puoi implementare l'integrazione in due modi:

• Integrazione diretta: tu, in qualità di inserzionista, implementi direttamente l'API Conversions.
• Integrazione come piattaforma: tu, in qualità di partner di marketing, offri l'API Conversions come servizio ai clienti.

Tramite integrazione diretta

Passaggio 1: configurazione dei requisiti

Prima di usare l'API Conversions, configura le seguenti risorse:

Una volta preparate le risorse, procedi con il passaggio di implementazione dell'API. Ricorda di salvare gli ID delle risorse, poiché li usi nelle chiamate all'API.

Passaggio 2: implementazione dell'API

Una volta soddisfatti i requisiti, passa al processo di implementazione. Quando crei l'API Conversions, consulta sempre la documentazione per gli sviluppatori.

Chiamate di prova (opzionali)

Se usi l'API per la prima volta, inizia da una chiamata di prova. Per farla, è necessario avere un payload e un metodo per effettuare chiamate all'API. Una volta completata la chiamata, consulta Gestione eventi per verificare che sia andata come previsto.

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

Dopo aver completato la prima chiamata, verifica i tuoi eventi in Gestione eventi > Il tuo pixel > Panoramica.

Una volta controllati gli eventi di prova in Gestione eventi, procedi con il passaggio Invio e verifica degli eventi.

Invio e verifica degli eventi

Per iniziare a inviare gli eventi, effettua una richiesta POST al segmento /events dell'API. Aggiungi un payload alla chiamata: se hai bisogno di aiuto per generarlo, accedi allo strumento di assistenza per il payload. Consulta le risorse seguenti per maggiori informazioni ed esempi di codice:

• Utilizzo dell'API > Inviare richieste
• Eventi ignorati
• Tempo di caricamento vs data e ora della transazione relativa all'evento
• Richieste batch
• Hashing

Dopo aver iniziato a inviare gli eventi, accedi a Gestione eventi e verifica che abbiamo ricevuto gli eventi inviati. Scopri come verificare gli eventi.

Se l'implementazione è complementare a un pixel del browser, passa alle impostazioni di deduplicazione. In caso contrario, il passaggio è completato. Consulta il supporto in caso di domande.

Passaggio 3: aggiunta dei parametri per la deduplicazione

Se invii eventi identici dal pixel e tramite l'API Conversions, devi configurare la deduplicazione per gli eventi inviati da entrambi i canali. Innanzitutto, consulta la documentazione per gli sviluppatori per capire come funziona la deduplicazione.

Deduplicazione basata sugli eventi

Se troviamo la stessa combinazione di chiavi server (event_id, event_name) e di chiavi browser (eventID, event) inviate allo stesso ID del pixel entro 48 ore, escludiamo gli eventi duplicati inviati successivamente.

Per assicurarti che gli eventi siano deduplicati:

• Per gli eventi corrispondenti, assicurati che i seguenti parametri siano impostati sullo stesso valore:

  • event_id dall'evento del server e eventID dall'evento del browser
  • event_name dagli eventi del server e del browser
• Una volta inviati gli eventi duplicati, consulta Gestione eventi per vedere se vengono ignorati gli eventi corretti.
• Assicurati che ogni evento unico inviato sia tramite il pixel sia tramite l'API Conversions abbia il suo event_id. L'ID non deve essere condiviso con altri eventi.

Alternativa alla deduplicazione basata sugli eventi

Anche se l'ID evento rimane sempre il modo migliore per deduplicare gli eventi, si tratta di un'implementazione piuttosto complessa. Sono disponibili soluzioni alternative che prevedono l'uso di parametri fbp o external_id. Se hai configurato il passaggio di parametri fbp o external_id sia tramite il browser sia tramite il server, deduplichiamo automaticamente gli eventi qualora individuiamo lo stesso evento con gli stessi parametri fbp o external_id entro 48 ore.

Passaggio 4 opzionale: esplorazione delle funzioni dell'SDK Business

L'SDK di Meta Business offre funzioni avanzate progettate appositamente per gli utenti dell'API Conversions:

• Richieste asincrone: usa questa funzione se non vuoi bloccare l'esecuzione del tuo programma in attesa del completamento di una richiesta. In questo modo, puoi effettuare la richiesta e ricevere un segnale dal server una volta completata. In attesa della risposta, il programma rimane in esecuzione.
• Batch simultanei: sfrutta le richieste asincrone per aumentare il throughput utilizzando le risorse in maniera più efficiente. Crea richieste in batch per supportare casi d'uso come richieste eventi, cron job e molto altro.
• Interfaccia di servizio HTTP: sovrascrivi il servizio HTTP predefinito dell'SDK Business e implementa il tuo servizio personalizzato con il metodo o la libreria che preferisci.

Integrazione come piattaforma

Le seguenti istruzioni sono destinate ai partner che offrono l'API Conversions come servizio per gli inserzionisti.

Passaggio 1: configurazione dei requisiti

L'app deve avere le seguenti funzioni e autorizzazioni:

• Livello di accesso: Accesso avanzato
• Funzione: Accesso standard Gestione delle inserzioni
• Autorizzazioni: ads_management, pages_read_engagement e ads_read

Passaggio 2: invio degli eventi per conto dei clienti

Innanzitutto, segui le istruzioni per l'integrazione diretta e testala. Dopodiché, richiedi l'autorizzazione per inviare gli eventi per conto dei clienti. Hai a disposizione le seguenti opzioni di autenticazione:

Metodo Estensione Meta Business (consigliato)

L'estensione Meta Business restituisce tutte le informazioni necessarie per inviare eventi per conto del cliente attraverso il processo seguente. L'estensione Meta Business fornisce un endpoint per recuperare i token d'accesso dell'utente del sistema creati nel Business Manager del cliente. Il processo include le autorizzazioni per inviare eventi del server e avviene in maniera automatica e sicura.

L'endpoint richiede un token d'accesso dell'utente come parametro di input. I nuovi utenti con estensione Meta Business devono chiamare questo endpoint per recuperare il token d'accesso dell'utente del sistema una volta configurata l'estensione. 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

Chiedi al cliente di creare manualmente un token d'accesso dell'utente del sistema tramite l'API Conversions dalle impostazioni del pixel. Invia quindi gli eventi al pixel dell'inserzionista usando quel token.

Un utente del sistema o un utente del 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 del sistema o dell'utente del sistema con funzioni di amministratore.

Condivisione del pixel al Business Manager del partner da parte del cliente

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

Passaggio 3: attribuzione degli eventi alla tua piattaforma

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. Se sei un partner con contratto, collabora con il tuo rappresentante di Meta per concordare un identificativo per la tua piattaforma. Questo valore deve essere in un formato che non superi i 23 caratteri e includa almeno due lettere dell'alfabeto. Invialo quindi con ogni evento del server.

Assistenza

Per tutti i partner

Consulta le informazioni sul debugging e gli articoli del Centro assistenza per le aziende.

Per i partner con contratto

Fornisci le seguenti informazioni al tuo rappresentante di Meta per metterlo nelle condizioni di aiutarti con il test delle integrazioni e la risoluzione dei problemi: ID Business Manager, ID dell'app, ID del pixel.

Documentazione sull'API

• Primi passi: testa l'API dal tuo Business Manager
• Utilizzo dell'API
• Best practice - API Conversions
• Configurazione dell'API Conversions come piattaforma
• Eventi standard di Meta
• Eventi personalizzati di Meta
• Parametri
• Strumento di assistenza per il payload
• Opzioni di elaborazione dei dati per l'API Conversions e l'API Offline Conversions
• Scelta dell'API App Events per eseguire l'ottimizzazione per gli eventi nell'app
• Scelta dell'API Offline Conversions per le vendite in negozio (gli eventi offline diversi dalle vendite in negozio sono idonei per l'API Conversions)