API Attribution Reporting: guida all'integrazione

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Developer Preview o Beta per selezionare la versione del programma che stai utilizzando, poiché 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 cross-party. Rispetto ai design comuni di oggi, gli implementatori dell'API Attribution Reporting devono tenere conto di alcune importanti considerazioni di alto livello:

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

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

In questa pagina, utilizziamo origine per rappresentare un clic o una visualizzazione e trigger per rappresentare una conversione.

Il seguente grafico mostra le diverse opzioni del flusso di lavoro per l'integrazione dell'attribuzione. Le sezioni elencate nella stessa colonna (cerchiate in verde) possono essere elaborate in parallelo. Ad esempio, il coinvolgimento dei partner può essere eseguito contemporaneamente all'attribuzione a livello di evento da app ad app.

Prerequisiti e configurazione

Completa i passaggi descritti in questa sezione per comprendere meglio l'API Attribution Reporting. Questi passaggi ti consentono di raccogliere risultati significativi quando utilizzi l'API nell'ecosistema della tecnologia pubblicitaria.

Familiarizzare con l'API

1. Leggi la proposta di progettazione per familiarizzare 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 di cui avrai bisogno per i tuoi casi d'uso.
3. Registrati per ricevere aggiornamenti sull'API Attribution Reporting. In questo modo, potrai rimanere al corrente sulle nuove funzionalità introdotte nelle versioni future.

Configurare e testare l'app di esempio

1. Quando è tutto pronto per iniziare l'integrazione, configura l'ultima anteprima per gli sviluppatori in Android Studio.
2. Configura endpoint del server di simulazione per le registrazioni di eventi e le consegne dei report. Abbiamo fornito dei mock-up 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 attivatori eseguendo e utilizzando l'app di esempio e dopo che è trascorso il periodo di tempo impostato, 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 dei job di generazione dei report.
3. Esamina i risultati dell'attribuzione da app ad app. Verifica che i dati in questi risultati siano quelli previsti sia per gli scenari di ultimo tocco sia per quelli post-installazione.
4. Dopo aver capito come funzionano insieme l'API client e il server, utilizza l'app di esempio come guida per la tua integrazione. Configura il tuo server di produzione e aggiungi chiamate di registrazione agli eventi alle tue app.

Pre-integrazione

Registra la tua organizzazione a Privacy Sandbox su Android. Questa registrazione è progettata per impedire la duplicazione non necessaria di piattaforme di tecnologie pubblicitarie, che consentirebbe l'accesso a più informazioni del necessario sulle attività dell'utente.

Coinvolgimento dei partner

I partner di tecnologia pubblicitaria (MMP/SSP/DSP) spesso creano soluzioni di attribuzione integrate. I passaggi descritti in questa sezione ti aiutano a prepararti per interagire al meglio con i tuoi partner tecnologici pubblicitari.

1. Pianifica un incontro 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 partner di misurazione per definire le tempistiche di integrazione, dai test iniziali all'adozione.
3. Chiarisci con i partner di misurazione quali aree coprirete 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 principali includono quanto segue:
   • In che modo i partner di misurazione registreranno le origini dell'attribuzione con l'API Attribution Reporting?
   • In che modo le reti di tecnologia pubblicitaria registrano i trigger con l'API Attribution Reporting?
   • In che modo ogni tecnologia pubblicitaria convaliderà le richieste API e restituirà le risposte per completare le registrazioni di origine e trigger?
   • Esistono report che devono essere condivisi tra 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 alla deduplicazione delle conversioni o all'allineamento delle chiavi di aggregazione?
6. Se l'attribuzione da app a web è applicabile, pianifica una discussione con i partner di misurazione sul web per discutere la progettazione, i test e l'adozione dell'API Attribution Reporting. Fai riferimento alle domande del passaggio precedente quando inizi le conversazioni con i partner web.

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

Questa sezione ti aiuta a configurare un'attribuzione di base da app ad app con report a livello di evento nella tua app o nel tuo SDK. Il completamento di questa sezione è obbligatorio prima di poter iniziare l'attribuzione del server di aggregazione di prototipi.

1. Configura un server di raccolta per i record degli eventi. Puoi farlo utilizzando la specifica fornita per generare un server di test o configurare il tuo server con il codice del server di esempio.
2. Aggiungi chiamate di eventi di registrazione dell'origine al tuo SDK o alla tua app quando vengono mostrati gli annunci.
   • Le considerazioni critiche includono quanto segue:
     • Verifica che gli ID evento sorgente siano disponibili e passati correttamente alle chiamate API di registrazione della sorgente.
     • Verifica di poter passare anche un `InputEvent` per registrare le origini dei clic.
     • Determina come configurare la priorità dell'origine per diversi tipi di eventi. Ad esempio, assegna una priorità elevata agli eventi considerati di alto valore, come i clic rispetto alle visualizzazioni.
     • Il valore predefinito per la scadenza è OK per i test. In alternativa, è possibile configurare finestre di scadenza diverse.
     • Per i test, puoi lasciare i filtri e le finestre di attribuzione come predefiniti.
   • Le considerazioni facoltative includono quanto segue:
     • Progetta le chiavi di aggregazione se sono pronte.
     • Considera la tua strategia di reindirizzamento quando stabilisci come vuoi collaborare con altri partner di misurazione.
3. Aggiungi eventi trigger di registrazione al tuo SDK o alla tua app per registrare gli eventi di conversione.
   • Le considerazioni critiche includono quanto segue:
     • Definisci i dati di attivazione, tenendo conto della fedeltà limitata restituita: in che modo ridurrai il numero di tipi di conversione necessari ai tuoi inserzionisti per i tre bit disponibili per i clic e il bit disponibile per le visualizzazioni?
     • Limiti ai trigger disponibili nei report sugli eventi: come prevedi di ridurre il numero totale di conversioni per origine che puoi ricevere nei report sugli eventi?
   • Le considerazioni facoltative includono:
     • Salta la creazione di chiavi di deduplicazione finché non esegui test di accuratezza.
     • Salta la creazione di chiavi e valori di aggregazione finché non sarà disponibile il supporto per i test di simulazione.
     • Salta i reindirizzamenti finché non avrai stabilito come vuoi collaborare con altri partner di misurazione.
     • La priorità del trigger non è essenziale per i test.
     • I filtri possono essere ignorati per i test iniziali.
4. Verifica che vengano generati eventi di origine per gli annunci e che i trigger portino alla creazione di report sugli eventi.

Test di simulazione

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

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

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

1. Configura la libreria di simulazione della misurazione su una macchina locale.
2. Leggi le specifiche su come devono essere formattati i dati sulle conversioni per essere compatibili con il generatore di report simulati.
3. Progetta le chiavi di aggregazione in base ai requisiti aziendali.
   • Le considerazioni critiche includono quanto segue:
     • Considera le dimensioni critiche che i tuoi clienti o partner devono aggregare e concentra la tua valutazione su queste.
     • Determina il numero minimo di dimensioni aggregate e cardinalità necessari per i tuoi requisiti.
     • Verifica che i componenti della chiave lato origine e lato trigger non superino i 128 bit.
     • Se le tue soluzioni prevedono di contribuire a più valori per evento trigger, assicurati di scalare i valori in base al budget massimo di contribuzione, L1. In questo modo, l'impatto del rumore viene ridotto al minimo.
     • Ecco un esempio che illustra 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 geografico.
4. Esegui il generatore di report per creare report sugli eventi e aggregabili.
5. Esegui i report aggregabili tramite i server di aggregazione simulati per ottenere report di riepilogo.
6. Eseguire esperimenti di utilità:
   • Confronta i totali delle conversioni dei 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 dei report su una porzione ampia e rappresentativa della base di inserzionisti.
   • Esegui il retraining dei modelli in base ai dati dei report a livello di evento e, potenzialmente, ai dati dei report riepilogativi. Confronta l'accuratezza con i modelli creati su dati di addestramento storici.
   • Prova diverse strategie di batching e vedi come influiscono sui risultati.
     • Le considerazioni critiche includono quanto segue:
     • Tempestività dei report riepilogativi per l'aggiustamento delle offerte.
     • Frequenze medie degli eventi attribuibili sul dispositivo. Ad esempio, gli utenti inattivi che tornano in base ai dati storici sugli eventi di acquisto.
     • Livello di rumore. Più batch significano un'aggregazione più piccola e un'aggregazione più piccola significa che viene applicato più rumore.

Attribuzione del server di aggregazione dei prototipi: configurazione

Questi passaggi ti consentiranno di ricevere report aggregabili degli eventi di origine e trigger.

1. Configura il server di aggregazione:
   • Configura il tuo account AWS.
   • Registrati al servizio di aggregazione con il tuo coordinatore.
   • Configura il server di aggregazione su AWS dai file binari forniti.
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. Configura 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 del server di aggregazione del prototipo: integrazione

Per procedere oltre questo punto, devi aver completato la sezione Attribuzione del server di aggregazione del prototipo: configurazione o la sezione Prototipo di attribuzione a livello di evento da app ad app**.

1. Aggiungi i dati della chiave di aggregazione agli eventi di origine e trigger. Probabilmente dovrai trasmettere più dati sull'evento dell'annuncio, ad esempio l'ID campagna, al tuo SDK o alla tua app da includere nella chiave di aggregazione.
2. Raccogli report aggregabili da app ad app dalle origini e attiva gli eventi che hai registrato con i dati delle chiavi di aggregazione.
3. Testa diverse strategie di batch mentre esegui questi report aggregabili tramite il server di aggregazione e scopri come influiscono sui risultati.

Iterare la progettazione con funzionalità opzionali

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

Utilizza l'API Debug per generare chiavi di debug (opzione consigliata)

1. L'impostazione di una chiave di debug ti consentirà di ricevere un report inalterato di un evento sorgente o 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 i comportamenti di attribuzione

1. Attribuzione per gli attivatori post-installazione
   • Questa funzionalità può essere utilizzata nel caso in cui i trigger post-installazione debbano essere attribuiti alla stessa origine attribuzione che ha generato l'installazione, anche se sono presenti altre origini attribuzione idonee che si sono verificate più di recente.
   • Ad esempio, potrebbe verificarsi un caso in cui un utente fa clic su un annuncio che genera un'installazione. Una volta installata, l'utente fa clic su un altro annuncio ed effettua un acquisto. In questo caso, la società di tecnologia pubblicitaria potrebbe voler attribuire l'acquisto al primo clic anziché al clic di riattivazione.
2. Utilizza i filtri per perfezionare i dati nei report a livello di evento
   • I filtri di conversione possono essere impostati in modo da ignorare i trigger selezionati ed escluderli dai report sugli eventi. Poiché esistono limiti al numero di trigger per origine attribuzione, i filtri ti consentono di includere solo i trigger che forniscono le informazioni più utili nei report sugli eventi.
   • I filtri possono essere utilizzati anche per escludere selettivamente alcuni trigger, ignorandoli di fatto. Ad esempio, se hai una campagna che ha come target le installazioni di app, potresti voler filtrare i trigger post-installazione in modo che non vengano attribuiti alle sorgenti di quella campagna.
   • I filtri possono essere utilizzati anche per personalizzare i dati dei trigger in base ai dati di origine. Ad esempio, una sorgente può specificare "product" : ["1234"], dove product è la chiave del filtro e 1234 è il valore. Qualsiasi trigger con una chiave di filtro "product" che ha un valore diverso da "1234" viene ignorato.
3. Priorità personalizzata di origine e trigger
   • Nel caso in cui più origini di attribuzione possano essere associate a un trigger o più trigger possano essere attribuiti a un'origine, puoi utilizzare un numero intero a 64 bit con segno per dare la priorità a determinate attribuzioni di origine o trigger rispetto ad altre.

Collaborare con MMP e altri

1. Reindirizzamenti ad altre terze parti per eventi di origine e trigger
   • Puoi impostare URL di reindirizzamento per consentire a più piattaforme di tecnologia pubblicitaria di registrare una richiesta. Può essere utilizzato per attivare la deduplicazione cross-network nell'attribuzione.
2. Chiavi di deduplicazione
   • Quando un inserzionista utilizza più piattaforme di tecnologia pubblicitaria per registrare lo stesso evento trigger, è possibile utilizzare una chiave di deduplicazione per distinguere questi report ripetuti. Se non viene fornita alcuna chiave di deduplicazione, i trigger duplicati potrebbero essere segnalati a ogni piattaforma di tecnologia pubblicitaria come unici.

Utilizzare la misurazione multipiattaforma

1. Attribuzione cross-app e web (disponibile alla fine del quarto trimestre)
   • Supporta i casi d'uso in cui un utente vede un annuncio in un'app e poi effettua una conversione in un browser mobile o in un browser per app o viceversa.