API Attribution Reporting: guida all'integrazione

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma a cui stai lavorando, in quanto le istruzioni possono variare.

L'API Attribution Reporting è progettata per supportare casi d'uso chiave per l'attribuzione e la misurazione delle conversioni nelle app e sul web, senza fare affidamento su identificatori di utenti trasversali. Rispetto ai progetti comuni oggi, gli utenti che implementano l'API Attribution Reporting dovrebbero tenere conto di alcune importanti considerazioni di alto livello:

  • I report a livello di evento includono dati sulle conversioni a bassa precisione. Un numero ridotto di valori di conversione funziona bene.
  • I report aggregati includono dati sulle conversioni ad alta fedeltà. Le soluzioni devono progettare chiavi di aggregazione in base alle tue esigenze aziendali e al limite di 128 bit.
  • I modelli e l'elaborazione dei dati della tua soluzione devono tenere conto dei limiti di frequenza per i trigger disponibili, dei ritardi per l'invio degli eventi di trigger e del rumore applicato dall'API.

Per aiutarti con la pianificazione dell'integrazione, questa guida fornisce una visione completa, che potrebbe includere funzionalità non ancora implementate nella fase attuale di Privacy Sandbox su Anteprima per gli sviluppatori Android. In questi casi, vengono fornite linee guida sulla tempistica.

In questa pagina, utilizziamo source per rappresentare un clic o una visualizzazione e attivatore per rappresentare una conversione.

Il grafico riportato di seguito mostra le diverse opzioni del flusso di lavoro per l'integrazione dell'attribuzione. È possibile lavorare in parallelo sulle sezioni elencate nella stessa colonna (cerchiate in verde); ad esempio, il coinvolgimento dei partner può avvenire contemporaneamente all'attribuzione a livello di evento da app ad app.

Diagramma del flusso di lavoro di integrazione di Attribution

Figura 1. Il flusso di lavoro di integrazione dell'attribuzione.

Prerequisiti e configurazione

Completa i passaggi in questa sezione per comprendere meglio l'API Attribution Reporting. Questi passaggi ti consentiranno di raccogliere risultati significativi quando utilizzi l'API nell'ecosistema ad tech.

Acquisire familiarità con l'API

  1. Leggi la proposta di progettazione per acquisire familiarità con l'API Attribution Reporting e le sue funzionalità.
  2. Leggi la guida per gli sviluppatori per scoprire come incorporare il codice e le chiamate API necessarie per i tuoi casi d'uso.
  3. Invia eventuali feedback per la documentazione, in particolare riguardo alle domande aperte.
  4. Iscriviti per ricevere aggiornamenti sull'API Attribution Reporting. Questo ti aiuterà a rimanere al corrente sulle nuove funzionalità che verranno introdotte nelle release future.

Configurare e testare l'app di esempio

  1. Quando è tutto pronto per iniziare l'integrazione, inizia a utilizzare l'Anteprima per sviluppatori più recente in Android Studio.
  2. Configura endpoint server fittizi per le registrazioni agli eventi e le pubblicazioni dei report. Abbiamo fornito delle simulazioni che puoi utilizzare insieme agli strumenti disponibili online.
  3. Scarica ed esegui il codice nella nostra app di esempio per acquisire familiarità con la registrazione di origini e trigger.
    1. Imposta la finestra temporale per l'invio dei report. L'API supporta finestre di 2 giorni, 7 giorni o un periodo personalizzato compreso tra 2 e 30 giorni.
    2. Dopo aver registrato origini e trigger eseguendo e utilizzando l'app di esempio e che il periodo di tempo impostato sia trascorso, verifica di aver ricevuto un report a livello di evento e un report aggregabile criptato. Se devi eseguire il debug dei report, puoi generarli più rapidamente forzando l'esecuzione di job di reporting.
    3. Esamina i risultati dell'attribuzione da app ad app. Verifica che i dati in questi risultati siano quelli previsti sia per le richieste di ultimo touchpoint sia per quelle post-installazione.

  4. Dopo aver capito come funzionano insieme l'API client e il server, utilizza l'app di esempio come esempio per guidare la tua integrazione. Configura il tuo server di produzione e aggiungi le chiamate di registrazione degli eventi alle tue app.

Pre-integrazione

Registra la tua organizzazione a Privacy Sandbox su Android. Questa registrazione è progettata per evitare duplicati non necessari di piattaforme di tecnologia pubblicitaria, il che consentirebbe di accedere a più informazioni del necessario sulle attività dell'utente.

Coinvolgimento dei partner

I partner di ad tech (MMP/SSP/DSP) spesso creano soluzioni di attribuzione integrate. I passaggi in questa sezione ti aiutano a prepararti per il successo interagendo con i tuoi partner di tecnologia pubblicitaria.

  1. Pianifica una discussione con i tuoi principali partner di misurazione per discutere dei test e dell'adozione dell'API Attribution Reporting. I partner di misurazione possono includere reti di tecnologia pubblicitaria, SSP, DSP, inserzionisti o qualsiasi altro partner con cui collabori o con cui vorresti collaborare.
  2. Collabora con i tuoi partner di misurazione per definire le tempistiche per l'integrazione, dal test iniziale all'adozione.
  3. Chiarisci con i tuoi partner di misurazione le aree che verranno trattati da ciascuno nella progettazione dell'attribuzione.
  4. Stabilisci canali di comunicazione tra i partner di misurazione per sincronizzare le tempistiche e i test end-to-end.
  5. Progetta flussi di dati di alto livello tra i partner di misurazione. Le considerazioni chiave includono quanto segue:
    • In che modo i partner di misurazione registrano le origini di attribuzione con l'API Attribution Reporting?
    • In che modo le reti di tecnologia pubblicitaria registrano gli attivatori con l'API Attribution Reporting?
    • In che modo ogni ad tech convaliderà le richieste API e restituirà risposte per completare l'origine e attivare le registrazioni?
    • Ci sono report che devono essere condivisi tra i partner al di fuori dell'API Attribution Reporting?
    • Sono necessari altri punti di integrazione o allineamento tra i partner? Ad esempio, tu e i tuoi partner dovete lavorare sulla deduplicazione delle conversioni o allinearvi alle chiavi di aggregazione?
  6. Se è applicabile l'attribuzione da app a web, pianifica una discussione con i partner di misurazione sul web per discutere di progettazione, test e adozione dell'API Attribution Reporting. Fai riferimento alle domande del passaggio precedente quando inizi le conversazioni con i partner web.

Prototipazione dell'attribuzione a livello di evento da app ad app

Questa sezione ti aiuta a impostare un'attribuzione di base da app ad app con report a livello di evento nella tua app o nell'SDK. È necessario completare questa sezione prima di poter iniziare a prototipare l'attribuzione del server di aggregazione.

  1. Configura un server di raccolta per i record di eventi. A tale scopo, puoi utilizzare le specifiche fornite per generare un server fittizio oppure configurare il tuo server con il codice server di esempio.
  2. Aggiungi le chiamate degli eventi di origine della registrazione all'SDK o all'app quando vengono mostrati gli annunci.
    • Alcune considerazioni critiche includono:
      • Assicurati che gli ID evento di origine siano disponibili e passati correttamente alle chiamate API di registrazione dell'origine.
      • Assicurati di poter anche passare un "InputEvent" per registrare le origini dei clic.
      • Stabilisci la modalità di configurazione della priorità di origine per i diversi tipi di eventi. Ad esempio, assegna una priorità elevata agli eventi considerati di alto valore, come i clic sulle visualizzazioni.
      • Il valore predefinito per la scadenza è accettabile per i test. In alternativa, è possibile configurare diverse finestre di scadenza.
      • I filtri e le finestre di attribuzione possono essere lasciati come predefiniti per i test.
    • Alcune considerazioni facoltative includono quanto segue:
      • Progetta le chiavi di aggregazione se è tutto pronto.
      • Valuta la tua strategia di reindirizzamento quando stabilisci come vuoi collaborare con altri partner di misurazione.
  3. Aggiungi registra gli eventi di trigger all'SDK o all'app per registrare gli eventi di conversione.
    • Alcune considerazioni critiche includono:
    • Alcune considerazioni facoltative includono quanto segue:
      • Salta la creazione di chiavi di deduplicazione finché non esegui i test di accuratezza.
      • Salta la creazione di chiavi e valori di aggregazione finché non sarà pronto il supporto per i test di simulazione.
      • Salta i reindirizzamenti finché non stabilisci come vuoi collaborare con altri partner di misurazione.
      • La priorità dell'attivatore non è essenziale per i test.
      • È probabile che i filtri vengano ignorati per il test iniziale.
  4. Verifica che gli eventi di origine vengano generati per gli annunci e che gli attivatori portino alla creazione di report sugli eventi.

Test della simulazione

Questa sezione ti illustrerà come testare l'impatto che il trasferimento delle conversioni attuali ai report aggregabili sugli eventi potrebbe avere sui sistemi di generazione di report e ottimizzazione. In questo modo, potrai iniziare i test di impatto prima di completare l'integrazione.

Il test viene eseguito simulando la generazione di report aggregabili sugli eventi in base ai record storici delle conversioni in tuo possesso, per poi ottenere i risultati aggregati da un server di aggregazione simulato. Questi risultati possono essere confrontati con i numeri storici delle conversioni per vedere come potrebbe cambiare l'accuratezza dei report.

I modelli di ottimizzazione, come i calcoli del tasso di conversione previsto, possono essere addestrati su questi report al fine di confrontare l'accuratezza di questi modelli rispetto a quelli basati sui dati attuali. È anche un'opportunità per sperimentare diverse strutture delle chiavi di aggregazione e il loro impatto sui risultati.

  1. Configura la libreria di simulazione di misurazione su una macchina locale.
  2. Leggi le spec su come devono essere formattati i dati sulle conversioni per essere compatibili con il generatore di report simulato.
  3. Progetta le chiavi di aggregazione in base ai requisiti aziendali.
    • Alcune considerazioni critiche includono:
      • Considera le dimensioni critiche di cui i tuoi clienti o partner hanno bisogno per aggregare e concentrare la tua valutazione su queste.
      • Determina il numero minimo di dimensioni e cardinalità aggregate necessarie per i tuoi requisiti.
      • Assicurati che le parti chiave lato origine e lato trigger non superino i 128 bit.
      • Se le soluzioni prevedono il contributo a più valori per evento di trigger, assicurati di scalare i valori rispetto al budget di contribuzione massimo, L1. In questo modo, potrai ridurre al minimo l'impatto del rumore.
      • Ecco un esempio che descrive in dettaglio l'impostazione di una chiave per raccogliere i conteggi aggregati delle conversioni a livello di campagna e di una chiave per raccogliere i valori di acquisto aggregati a livello di area geografica.
  4. Esegui il generatore di report per creare report aggregabili sugli eventi.
  5. Esegui i report aggregabili tramite i server di aggregazione simulati per ricevere report di riepilogo.
  6. Esegui esperimenti di utilità:
    • Confronta i totali delle conversioni provenienti dai report a livello di evento e di riepilogo con i dati storici sulle conversioni per determinare l'accuratezza dei report sulle conversioni. Per ottenere risultati ottimali, esegui i test e i confronti relativi ai report su una parte ampia e rappresentativa della base di inserzionisti.
    • Reimposta i modelli in base ai dati dei report a livello di evento e ai dati dei report potenzialmente di riepilogo. Confronta l'accuratezza con i modelli basati su dati di addestramento storici.
    • Prova diverse strategie di raggruppamento e osserva come influiscono sui risultati.
      • Alcune considerazioni critiche includono:
      • Tempestività dei report di riepilogo per l'aggiustamento delle offerte.
      • Frequenze medie di eventi attribuibili sul dispositivo. Ad esempio, gli utenti non più attivi che ritornano in base ai dati storici degli eventi di acquisto.
      • Livello di rumore. Più batch indicano un'aggregazione più piccola, mentre un'aggregazione più piccola comporta l'applicazione di più rumore.

Attribuzione server di aggregazione prototipo: configurazione

Questi passaggi assicurano che tu sia in grado di ricevere report aggregabili degli eventi di origine e trigger.

  1. Configura il server di aggregazione:
  2. Progetta le chiavi di aggregazione in base ai requisiti aziendali. Se hai già completato questa attività nella sezione a livello di evento da app ad app, puoi saltare questo passaggio.
  3. Configurare un server di raccolta per i report aggregabili. Se ne hai già creato uno nella sezione a livello di evento da app ad app, puoi riutilizzarlo.

Attribuzione server di aggregazione prototipo: integrazione

Per andare oltre questo punto, devi aver completato la sezione Prototype Aggregation Server Attribution: Configurazione o Prototype App to App Event-Level Attribution**.

  1. Aggiungi dati chiave di aggregazione all'origine e attiva gli eventi. È probabile che sia necessario trasferire più dati sull'evento dell'annuncio, ad esempio l'ID campagna, nell'SDK o nell'app per includerli nella chiave di aggregazione.
  2. Raccogli report aggregabili dall'app all'app e attiva gli eventi che hai registrato con i dati chiave di aggregazione.
  3. Testa diverse strategie di batch mentre esegui questi report aggregabili tramite il server di aggregazione e osserva l'impatto che hanno sui risultati.

Ripeti il design con funzionalità facoltative

Di seguito sono riportate ulteriori funzionalità che puoi includere nella tua soluzione di misurazione.

  1. L'impostazione di una chiave di debug ti consentirà di ricevere un report inalterato di un'origine o di un evento di trigger insieme ai report generati dall'API Attribution Reporting. Puoi utilizzare le chiavi di debug per confrontare i report e trovare bug durante l'integrazione.

Personalizzare il comportamento dell'attribuzione

  1. Attribuzione per trigger post-installazione
    • Questa funzionalità può essere utilizzata nel caso in cui gli attivatori post-installazione debbano essere attribuiti alla stessa origine di attribuzione che ha generato l'installazione, anche se esistono altre origini di attribuzione idonee che si sono verificate più di recente.
    • Ad esempio, può accadere che un utente faccia clic su un annuncio che genera un'installazione. Al termine dell'installazione, l'utente fa clic su un altro annuncio ed effettua un acquisto. In questo caso, l'azienda di ad tech potrebbe voler attribuire l'acquisto al primo clic anziché al clic di ricoinvolgimento.
  2. Utilizzare i filtri per ottimizzare i dati nei report a livello di evento
    • Puoi impostare i filtri di conversione in modo da ignorare gli attivatori selezionati ed escluderli dai report sugli eventi. Poiché esistono limiti al numero di attivatori per origine di attribuzione, i filtri ti consentono di includere solo gli attivatori che forniscono le informazioni più utili nei report sugli eventi.
    • I filtri possono essere usati anche per filtrare selettivamente alcuni attivatori, ignorandoli effettivamente. Ad esempio, se hai una campagna che ha come target le installazioni di app, potresti voler escludere gli attivatori post-installazione in modo che non vengano attribuiti alle sorgenti di tale campagna.
    • I filtri possono essere utilizzati anche per personalizzare i dati degli attivatori in base ai dati di origine. Ad esempio, un'origine può specificare "product" : ["1234"], dove product è la chiave di filtro e 1234 è il valore. Qualsiasi attivatore con una chiave filtro di "prodotto" con un valore diverso da "1234" viene ignorato.
  3. Priorità dell'origine e dell'attivatore personalizzate
    • Nel caso in cui a un attivatore sia possibile associare più origini di attribuzione o più attivatori a un'origine, puoi utilizzare un numero intero firmato a 64 bit per dare la priorità a determinate attribuzioni di origini/attivatori rispetto ad altre.

Collaborazione con MMP e altri

  1. Reindirizzamenti ad altre terze parti per eventi di origine e di attivazione
    • Puoi impostare gli URL di reindirizzamento per consentire a più piattaforme di tecnologia pubblicitaria di registrare una richiesta. Questa opzione può essere utilizzata per attivare la deduplicazione su più reti nell'attribuzione.
  2. Chiavi di deduplicazione
    • Quando un inserzionista utilizza più piattaforme ad tech per registrare lo stesso evento attivatore, può essere utilizzata una chiave di deduplicazione per distinguere questi report ripetuti. Se non viene fornita una chiave di deduplicazione, gli attivatori duplicati potrebbero essere segnalati come univoci per ogni piattaforma di tecnologia pubblicitaria.

Lavorare con la misurazione multipiattaforma

  1. Attribuzione tra app e web (disponibile a fine T4)
    • Supporta i casi d'uso in cui un utente vede un annuncio in un'app, quindi effettua una conversione in un browser mobile o di app o viceversa.