API App Events

App Events ti consente di monitorare le azioni che si verificano nella tua app mobile o sulla pagina web, come installazioni dell'app ed eventi di acquisto. Monitorando questi eventi puoi misurare le prestazioni delle inserzioni e creare un pubblico per la targetizzazione delle inserzioni.

Per informazioni sul monitoraggio degli eventi nell'app per la messaggistica aziendale, fai riferimento all'API App Events per la messaggistica aziendale nella nostra documentazione sulla Piattaforma Messenger.

Come funziona

Esistono tre tipi di eventi nell'app:

• Eventi registrati automaticamente: l'SDK di Facebook registra automaticamente installazioni dell'app, sessioni dell'app e acquisti in-app.
• Eventi standard: eventi popolari che Facebook ha creato per te.
• Eventi personalizzati: eventi creati da te specifici per la tua app.

Un evento nell'app è composto da tre parti:

1. name: una stringa obbligatoria che descrive l'evento. Il nome viene visualizzato nel registro eventi quando l'evento nell'app viene inviato ad Analytics.
2. valueToSum: un valore opzionale che Analytics aggiunge ad altri parametri di Value To Sum correlati agli eventi nell'app con lo stesso nome.
3. parameters: valori opzionali compresi con l'evento nell'app.

È possibile attribuire massimo 1000 nomi diversi agli eventi. Nota: una volta raggiunto questo limite, non vengono registrati nuovi tipi di evento. Se lo superi, potresti visualizzare l'errore 100 Invalid parameter al momento della registrazione. Tuttavia, è possibile disattivare eventi obsoleti. Per scoprire di più sui limiti degli eventi, consulta la sezione FAQ.

Prima di iniziare

Ecco cosa ti servirà:

• ID inserzionista, ID pubblicitario da un dispositivo Android o IDFA da un dispositivo Apple
• Un token d'accesso dell'app per consentire a Facebook di eseguire l'autenticazione. Non memorizzare il token d'accesso dell'app sul client.

Installazioni dell'app

Invia una richiesta POST dal tuo server all'endpoint /{app-id}/activities con i parametri application_tracking_enabled e advertiser_tracking_enabled:

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

In caso di azione eseguita correttamente, l'app riceve la seguente risposta:

{
  "success": true
}

Precisazioni

• Devi registrare una sola installazione per utente. Deduplica gli ID a livello di utente e di ID, se possibile.

Consulta la nostra Guida di riferimento per le attività dell'app per una lista dei parametri disponibili.

Abilitazione del monitoraggio delle inserzioni

Il campo advertiser_tracking_enabled specifica se una persona ha abilitato sul dispositivo il monitoraggio delle inserzioni. Il parametro è 0 per monitoraggio disabilitato o 1 per monitoraggio abilitato. Devi recuperare questi dati e restituirli a Facebook per determinare se il monitoraggio delle inserzioni può essere utilizzato per l'ottimizzazione o le conversioni. Meta utilizzerà i dati relativi agli eventi (raccolti dai partner sulle attività utente fuori da Meta) in accordo con la sua Normativa sui dati, dunque anche per i report pubblicitari, il rilevamento frodi e la creazione e il miglioramento dei prodotti (compresi i prodotti per la pubblicazione delle inserzioni), ma limiterà l'uso dei dati di quell'utente alla personalizzazione delle sue inserzioni. Per i dispositivi che eseguono versioni precedenti a iOS 6, questo parametro deve essere per impostazione predefinita su 1.

Consulta il riferimento Apple per AdSupport per ottenere lo stato del monitoraggio di un utente.

Lo snippet di codice seguente illustra come recuperare il valore del contrassegno "Monitoraggio abilitato".

Puoi ottenere l'impostazione attuale del contrassegno "Monitoraggio abilitato" dalla proprietà Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

Disabilitazione del monitoraggio delle inserzioni

Qualsiasi app può contenere un'impostazione che consenta agli utenti di disattivare il monitoraggio delle inserzioni al suo interno. Facebook chiede ai partner di includere questa opzione nel loro SDK e riportare la scelta dell'utente a Facebook unitamente all'evento di installazione o conversione. Facebook usa l'evento di installazione o di conversione per i report pubblicitari, ma consente di usarlo nell'ottimizzazione delle inserzioni in modo limitato. L'impostazione scelta dell'utente deve restare invariata a ogni avvio dell'app.

Eventi di conversione

Invia una richiesta POST all'endpoint /{app-id}/activities con l'elemento event impostato su CUSTOM_APP_EVENTS e imposta advertiser_tracking_enabled per ogni singolo evento. Uno tra i parametri advertiser_id e attribution è obbligatorio.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

In caso di azione eseguita correttamente, l'app riceve la seguente risposta:

{
  "success": true
}

Attribuzione

L'endpoint attribution restituisce gli eventi di installazione e conversione in base ai clic su un'inserzione in un periodo di tempo di 28 giorni. Gestione inserzioni utilizza un modello di attribuzione da 1 giorno dalla visualizzazione a 28 giorni dal clic e gli insight vengono visualizzati in base al momento dell'impression o del clic, non a quello di installazione o conversione. Questo aspetto è importante quando confronti i tuoi report con quelli di Gestione inserzioni di Facebook. Oltre alle richieste standard di eventi nell'app relative ai clic sull'inserzione, devi tenere a mente anche i seguenti scenari:

• Richieste di attribuzione di visualizzazioni: l'impostazione consider_views=TRUE restituisce i dati di attribuzione per gli eventi di installazione avvenuti entro 1 giorno dall'impression dell'inserzione, a condizione che l'account del Centro gestione account non abbia cliccato su un'inserzione in un periodo di 28 giorni. La risposta restituita sarà is_view_through=TRUE e view_time sostituirà click_time. Tutte le altre attribuzioni sono uguali a quelle dei dati di attribuzione per clic sulle inserzioni.

• Richieste inter-campagna: gli inserzionisti possono monitorare le prestazioni di tutte le inserzioni che hanno portato a un evento nell'app. Facebook invia richieste per eventi da campagne pubblicitarie purché l'obiettivo della campagna non sia impostato sull'installazione di app mobili o sull'interazione con tali app. Questi dati vengono visualizzati solo se l'inserzionista ha aggiunto l'app al campo "Mobile App Events Tracking" nell'inserzione.

• Caso d'uso: se il cliente desidera monitorare gli eventi di installazione generati dall'inserzione che rimanda a un post della Pagina o invita a cliccare su un sito web che reindirizza gli utenti a un sito per dispositivi mobili, può farlo in Gestione inserzioni: Facebook richiederà gli eventi di installazione dell'app rilevanti.

• Richieste cross-device: gli inserzionisti con app multipiattaforma ora possono vedere le installazioni dell'app generate dalle inserzioni sulle varie piattaforme.

• Caso d'uso: un utente clicca su un'inserzione di un'app per iPhone e poi la installa sul proprio iPad. Ciò consente di attribuire l'installazione dell'app per iPad all'inserzione per iPhone indipendentemente dalla targetizzazione dell'inserzione.

Associazione avanzata

L'associazione avanzata ti consente di inviare i dati dei clienti a Facebook, che il utilizzerà per determinare in modo più accurato quali account del Centro gestione account hanno intrapreso un'azione in risposta alla tua inserzione. Con questi dati, Facebook può abbinare gli eventi di conversione ai tuoi clienti per ottimizzare le tue inserzioni e creare gruppi di pubblico di remarketing più ampi.

Invia una richiesta POST all'endpoint /{app-id}/activities con il parametro ud impostato in modo che consenta di monitorare i dati dei cliente, come l'e-mail o il numero di telefono. Tutti i dati dei clienti devono essere sottoposti ad algoritmo di hashing; in caso contrario, Facebook li ignorerà. Assicurati di impostare advertiser_tracking_enabled per ogni singolo evento.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

In caso di azione eseguita correttamente, l'app riceve la seguente risposta:

{
  "success": true
}

Tutti i dati utente devono essere in formato hash con algoritmo SHA256 prima di essere inviati a Facebook. In caso contrario, Facebook li ignorerà.

Deduplicazione

Per gli eventi nell'app, applichiamo la stessa funzionalità di deduplicazione esistente per gli eventi web. La logica utilizza la deduplicazione basata sui campi event_id e event_name. Il parametro event_id è un identificativo in grado di distinguere in modo univoco gli eventi simili. ID evento inaccurati possono causare una deduplicazione errata della conversione, con conseguente impatto sul report sulle conversioni e sulle prestazioni della campagna.

Informazioni estese sul dispositivo

Puoi inviare informazioni sul dispositivo, come larghezza e altezza dello schermo, nella chiamata all'evento nell'app usando /{app-id}/activities?extinfo. I valori sono separati da virgole e devono essere nell'ordine indicizzato nella guida di riferimento /application/activites. Quando utilizzi extinfo, tutti i valori sono obbligatori.

• version deve essere a2 per Android
• version deve essere i2 per iOS

Riferimento

• Parametri ApplicationActivities
• Documentazione per sviluppatori Android: metriche di visualizzazione
• Documentazione per sviluppatori Android: archiviazione esterna
• Documentazione per sviluppatori Apple: metriche di visualizzazione
• Documentazione per sviluppatori Apple: archiviazione esterna
• Documentazione per sviluppatori Apple: dimensioni dello schermo

Ricezione di cookie per dispositivi mobili

Ti consigliamo di associare gli eventi nell'app a un advertiser_id. Per i dispositivi Android e i dispositivi iOS precedenti a iOS 6, puoi anche usare il parametro attribution impostato sui cookie per dispositivi mobili del dispositivo.

Nota: i cookie per dispositivi mobili non derivano da alcun attributo utente o dispositivo. Non sono permanenti e sono progettati per essere aggiornati di frequente. Non usare i cookie per dispositivi mobili per il retargeting delle inserzioni.

Android

Un cookie è una stringa alfanumerica di 22 caratteri casuali.

Acquisisci l'ID attribuzione Facebook usando ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Devi inoltre recuperare l'ID pubblicitario dell'app Android.

iOS

I cookie per dispositivi mobili sono creati dalle app Facebook per iOS tramite l'elemento CFUUIDCreateString e si tratta di una rappresentazione di stringa UUID a 128 bit.

Ottieni sia l'ID cookie sia l'IDFA e inviali a Facebook come identificativo:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

Header HTTP X-Forwarded-For

Se le richieste POST vengono effettuate da un luogo centrale come un server o proxy, fondamentalmente una chiamata da server a server, l'header HTTP X-Forwarded-For è obbligatorio per garantire che le informazioni su posizione e dispositivo siano accurate. Invia l'indirizzo IP del dispositivo, in formato IPv4 o IPv6, tramite il parametro dell'intestazione HTTP X-Forwarded-For in ognuna delle richieste di eventi nell'app inviate. Ciò consente di associare l'advertiser_id all'indirizzo IP corretto, che può quindi essere utilizzato nella nostra piattaforma.

Esempio IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

Esempio IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Test

1. Accedi a Gestione eventi.
2. Clicca sull'icona Origini dei dati a sinistra nella pagina.
3. Seleziona il nome e l'ID dei tuoi dati.
4. Clicca su Testa gli eventi e seleziona App come canale.
5. Invia una richiesta AE-API con il Tool di esplorazione per la API Graph.
6. Le tue interazioni saranno presto visibili nella tab Testa gli eventi.

Discrepanze

Se un cliente confronta i report di un Mobile Measurement Partner con quelli di Facebook e nota discrepanze, occorre verificare gli elementi seguenti:

Se Facebook riporta un numero minore di installazioni rispetto all'MMP:

• L'SDK di Facebook è integrato correttamente?
• Il cliente utilizza l'ID app errato?

Se Facebook riporta un numero maggiore di installazioni rispetto all'MMP:

• Le finestre di attribuzione sono le stesse? In genere, Facebook ha una finestra di attribuzione più ampia rispetto alla maggior parte dei Mobile Measurement Partner.
• L'SDK dell'MMP è integrato correttamente?
• Il cliente utilizza l'ID app errato?
• La discrepanza riguarda solo iOS 7? L'MMP riceve l'ID pubblicitario IDFA di Apple dal dispositivo e lo trasmette correttamente a Facebook?

Riferimento

Informazioni estese sulle attività dell'app

Per maggiori informazioni sulle informazioni estese sull'app, consulta la guida di riferimento /application/activites.

Parametri dei dati degli utenti

Nomi eventi standard

Parametri eventi standard

Altri contenuti da consultare

• App Events
• Best practice per App Events
• Gestione degli errori
• Conformità al GDPR
• Gestione inserzioni di Facebook
• Dashboard gestione app di Facebook