API Conversions per gli eventi nell'app

L'API Conversions consente agli inserzionisti di inviare eventi web, nell'app, nei punti vendita fisici e relativi alla messaggistica aziendale a Meta attraverso un unico endpoint anziché su più origini. Questo consolidamento semplificherà lo stack tecnologico degli inserzionisti e creerà una visione più completa in Gestione eventi di Meta usando i dataset.

Questa documentazione fornisce indicazioni per integrare gli eventi nell'app nell'API Conversions.

Prerequisiti

1. Dataset

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

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

Puoi effettuare la chiamata GET a https://graph.facebook.com /v16.0/{ads-pixel-id}/is_consolidated_container per rilevare se il dataset dell'inserzionista è consolidato e quindi idoneo per passare eventi nell'app tramite l'API Conversions.

2. 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

Invio degli eventi nell'app all'API Conversions

a. Collegamento dell'ID del dataset e dell'ID dell'app

In Gestione eventi ci sono due modi per collegare la tua app a un dataset:

Seleziona la tab "Origini dei dati", trova la tab "Impostazioni" della tua app ed effettua il collegamento.
Seleziona la tab "Origini dei dati", nella tab "Panoramica" della tua app, usa il pulsante "Collega a dataset" nella sezione "Tutte le attività".

Una volta completato il collegamento, il dataset include l'app collegata.

b. Campi obbligatori

Puoi fare riferimento qui all'attuale insieme di parametri che possono essere inviati tramite l'API Conversions. Per l'invio di eventi nell'app, i seguenti campi server_event possono essere condivisi nel payload:

Il parametro action_source deve contenere il valore app per gli eventi nell'app.
event_id è obbligatorio per il caso di configurazione della deduplicazione.
app_data fields
user_data fields
custom_data fields

Campi dati dell'app

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

Parametri delle informazioni dei clienti

Parametro	Descrizione
`anon_id` stringa	Non applicare l'algoritmo di hashing. L'ID di installazione. Questo campo rappresenta istanze uniche di installazione dell'app.
`madid` stringa	Non sottoporre a procedura di hashing. ID dell'inserzionista mobile, ID pubblicitario da un dispositivo Android o IDFA da un dispositivo Apple.

Dati personalizzati

Parametro	Descrizione
`description` stringa	Facoltativo. Stringa, descrizione dell'evento, personalizzata.
`level` stringa	Facoltativo. Stringa, livello di un gioco, personalizzato.
`max_rating_value`	Facoltativo. Long, limiti superiori di una scala di valutazione, ad esempio 5 su una scala a 5 stelle, personalizzato.
`success` booleano	Facoltativo. `1` per sì, `0` per no, personalizzato.

In sintesi, gli eventi nell'app condivisi usando l'API Conversions richiederanno i seguenti parametri dei dati:

action_source: deve essere impostato su "app". (Usando l'API Conversions, dichiari che il parametro action_source, per quanto ne sai, è accurato).
event_id: obbligatorio per la configurazione della deduplicazione, vedi i dettagli nella sezione "Configurazione della deduplicazione per più canali".
advertiser_tracking_enabled
application_tracking_enabled
extinfo

Di seguito un esempio di extinfo. Assicurati che tutti i sottoparametri siano compilati e in ordine sequenziale. Se manca qualcosa, usa una stringa vuota come segnaposto.

Nome del sottoparametro	Obbligatorio	Tipo di dati	Esempio
extinfo version	Sì	stringa	`i2` (la versione deve essere a2 per Android, i2 per iOS)
app package name	No	stringa	`com.facebook.sdk.samples.hellofacebook`
short version	No	stringa	`1.0`
long version	No	stringa	`1.0 long`
os version	Sì	stringa	`13.4.1`
device model name	No	stringa	`iPhone5,1`
locale	No	stringa	`En_US`
timezone abbr	No	stringa	`PDT`
carrier	No	stringa	`AT&T`
screen width	No	stringa	`320`
screen height	No	stringa	`568`
screen density	No	stringa	`2`
cpu core	No	stringa	`2`
external storage size	No	stringa	`13`
free space in external storage size	No	stringa	`8`
device time zone	No	stringa	`USA/New York`

c. Configurazione della deduplicazione per più canali

Il meccanismo di deduplicazione sarà necessario per rimuovere il traffico di eventi duplicati tra l'integrazione dell'API Conversions e tutte le altre integrazioni esistenti che hai con gli eventi nell'app, tra cui SDK, MMP e API App Events.

Per gli eventi nell'app, applichiamo la stessa funzionalità di deduplicazione esistente per gli eventi web. La logica sfrutta il campo event_id e la deduplicazione basata su event_name (eventi API Conversions e SDK/API App Events che hanno lo stesso event_id). Il parametro event_id è un identificatore che può distinguere in modo univoco eventi simili. ID evento inaccurati possono causare una deduplicazione errata della conversione, con conseguente impatto sul report sulle conversioni e sulle prestazioni della campagna.

Puoi consultare la seguente documentazione per gli sviluppatori per implementare la configurazione della deduplicazione:

Ecco un esempio di come registrare un evento personalizzato. Per farlo, passa il nome dell'evento come AppEvents.Name nell'SDK per iOS:

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

Per gli eventi di installazione dell'app, esiste già un meccanismo di deduplicazione che assicura che solo un'installazione sia attribuita nell'ultima finestra di 90 giorni. Manteniamo il primo evento e ignoriamo quelli successivi, indipendentemente dall'origine dell'azione da cui provengono. Non è necessario implementare la deduplicazione per gli eventi nell'app relativi agli eventi di installazione.

d. 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 del server dell'app. 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:

**Risoluzione dei problemi**

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

Quando applicabile, scegli app come origine dell'azione
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.