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 con cui stai lavorando, poiché le istruzioni possono variare.

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

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

Per aiutarti a pianificare l'integrazione, questa guida fornisce una visione completa, che potrebbe includere funzionalità non ancora implementate nella fase attuale di Privacy Sandbox in Android Developer Preview. In questi casi, vengono fornite indicazioni sulle tempistiche.

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

Il grafico seguente mostra le diverse opzioni di flusso di lavoro per l'integrazione dell'attribuzione. Le sezioni elencate nella stessa colonna (circolate 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.

Diagramma del flusso di lavoro di integrazione dell'attribuzione

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

Prerequisiti e configurazione

Completa i passaggi di 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 design 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 passo con le nuove funzionalità introdotte nelle release future.

Configura e testa l'app di esempio

  1. Quando è tutto pronto per iniziare l'integrazione, configura la versione più recente dell'anteprima per gli sviluppatori in Android Studio.
  2. Configura gli endpoint del server simulato per le registrazioni degli eventi e l'invio dei report. Abbiamo fornito simulazioni che puoi utilizzare insieme agli strumenti disponibili online.
  3. Scarica ed esegui il codice nella nostra app di esempio per familiarizzare con la registrazione di origini e attivatori.
    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 e aver eseguito e utilizzato l'app di esempio, nonché dopo 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 eseguendo forzatamente i job di generazione dei report.
    3. Esamina i risultati per l'attribuzione da app ad app. Verifica che i dati di questi risultati siano come previsti sia per le campagne last-touch sia per quelle post-installazione.

  4. Dopo aver compreso il funzionamento dell'API client e del 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 con Privacy Sandbox su Android. Questa registrazione è progettata per evitare la duplicazione non necessaria delle piattaforme di tecnologia pubblicitaria, 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 di adtech.

  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 ad tech, SSP, DSP, inserzionisti o qualsiasi altro partner con cui collabori attualmente o con cui vorresti collaborare.
  2. Collabora con i tuoi partner di misurazione per definire le tempistiche di integrazione, dai test iniziali all'adozione.
  3. Chiarisci con i tuoi partner di misurazione quali aree coprirà ciascuno nel design dell'attribuzione.
  4. Stabilisci canali di comunicazione tra i partner di misurazione per sincronizzarti su tempistiche e test end-to-end.
  5. Progettare 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 attribuzione con l'API Attribution Reporting?
    • In che modo le reti ad tech registreranno gli attivatori con l'API Attribution Reporting?
    • In che modo ogni fornitore di tecnologia pubblicitaria convaliderà le richieste API e restituirà le risposte per completare le registrazioni dell'origine e attivarle?
    • Esistono 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 per eliminare le duplicazioni delle conversioni o allinearvi sulle chiavi di aggregazione?
  6. Se l'attribuzione da app a web è applicabile, 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.

Prototipo di attribuzione a livello di evento da app ad app

Questa sezione ti aiuta a configurare un'attribuzione da app ad app di base con report a livello di evento nella tua app o nel tuo SDK. È necessario completare questa sezione prima di poter iniziare a eseguire il prototipaggio dell'attribuzione del server di aggregazione.

  1. Configura un server di raccolta per i record degli eventi. A questo scopo, puoi utilizzare la specifica fornita per generare un server simulato o configurare il tuo server con il codice di esempio del server.
  2. Aggiungi chiamate di eventi di registrazione dell'origine al tuo SDK o alla tua app quando vengono pubblicati gli annunci.
    • Le considerazioni fondamentali includono quanto segue:
      • Assicurati che gli ID evento di origine siano disponibili e trasmessi correttamente alle chiamate API di registrazione dell'origine.
      • Assicurati di poter passare anche un "InputEvent" per registrare le sorgenti di clic.
      • Determina come configurare la priorità dell'origine per diversi tipi di eventi. Ad esempio, assegna una priorità elevata agli eventi considerati di valore elevato, come i clic rispetto alle visualizzazioni.
      • Il valore predefinito per la scadenza è OK 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.
    • Le considerazioni facoltative includono quanto segue:
      • Progetta le chiavi di aggregazione se sono pronte.
      • Tieni presente la strategia di reindirizzamento quando decidi come collaborare con altri partner di misurazione.
  3. Aggiungi eventi di attivazione della registrazione al tuo SDK o alla tua app per registrare gli eventi di conversione.
    • Le considerazioni fondamentali includono quanto segue:
    • Le considerazioni facoltative includono quanto segue:
      • Salta la creazione delle chiavi di deduplica finché non esegui i 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 stabilisci come vuoi collaborare con altri partner di misurazione.
      • La priorità dell'attivatore non è essenziale per i test.
      • I filtri possono essere ignorati per i test iniziali.
  4. Verifica che gli eventi di origine vengano generati per gli annunci e che gli attivatori contribuiscano alla creazione di report sugli eventi.

Test di simulazione

Questa sezione illustra la procedura per testare l'impatto che il trasferimento delle conversioni attuali ai report aggregabili e sugli eventi potrebbe avere sui sistemi di generazione di report e ottimizzazione. In questo modo potrai iniziare i test sull'impatto prima di completare l'integrazione.

I test vengono eseguiti simulando la generazione di report aggregabili e sugli eventi in base ai record storici delle conversioni di cui disponi, per poi ottenere i risultati aggregati da un server di aggregazione simulato. Questi risultati possono essere confrontati con i numeri delle conversioni storiche per vedere in che modo 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 rispetto a quelli basati sui dati attuali. È anche un'occasione per sperimentare diverse strutture delle 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 simulato.
  3. Progetta le chiavi di aggregazione in base ai requisiti aziendali.
    • Le considerazioni fondamentali includono quanto segue:
      • Prendi in considerazione le dimensioni critiche che i tuoi clienti o partner devono aggregare e concentrati su queste per la valutazione.
      • Determina il numero minimo di dimensioni aggregate e cardinalità necessarie per i tuoi requisiti.
      • Assicurati che i componenti della chiave lato sorgente e lato trigger non superino i 128 bit.
      • Se le tue soluzioni prevedono il contributo a più valori per evento di attivazione, assicurati di scalare i valori in base al budget di contributo massimo, L1. In questo modo, l'impatto del rumore verrà ridotto al minimo.
      • Di seguito è riportato un esempio che illustra in dettaglio l'impostazione di una chiave per raccogliere i conteggi delle conversioni aggregate a livello di campagna e una chiave per raccogliere i valori di acquisto aggregati a livello geografico.
  4. Esegui il generatore di report per creare report aggregabili ed eventi.
  5. Esegui i report aggregabili tramite i server di aggregazione simulati per ottenere report di riepilogo.
  6. Esegui esperimenti di utilità:
    • Confronta i totali di conversione dei report a livello di evento e di riepilogo con i dati sulle conversioni storici per determinare l'accuratezza dei report sulle conversioni. Per risultati ottimali, esegui i test e i confronti dei report su una base di inserzionisti ampia e rappresentativa.
    • Addestrare nuovamente i modelli in base ai dati dei report a livello di evento e potenzialmente ai dati dei report di riepilogo. Confronta la precisione con i modelli creati su dati di addestramento storico.
    • Prova diverse strategie di raggruppamento e osserva in che modo influiscono sui tuoi risultati.
      • Le considerazioni fondamentali includono quanto segue:
      • Tempestività dei report di riepilogo per l'aggiustamento delle offerte.
      • Frequenze medie degli eventi attribuibili sul dispositivo. Ad esempio, gli utenti persi 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 del prototipo: configurazione

Questi passaggi ti consentiranno di ricevere report aggregabili della tua origine e di attivare gli eventi.

  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. 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 Prototipo di attribuzione del server di aggregazione: configurazione o la sezione Prototipo di attribuzione a livello di evento da app ad app**.

  1. Aggiungi i dati delle chiavi di aggregazione all'origine e attiva gli eventi. Probabilmente sarà necessario passare più dati sull'evento dell'annuncio, ad esempio l'ID campagna, all'SDK o all'app per includerli nella chiave di aggregazione.
  2. Raccogli report aggregabili da app ad app dall'origine e attiva gli eventi che hai registrato con i dati della chiave di aggregazione.
  3. Prova diverse strategie di raggruppamento durante l'esecuzione di questi report aggregabili tramite il server di aggregazione e scopri in che modo influiscono sui risultati.

Eseguire l'iterazione del design con funzionalità facoltative

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

  1. L'impostazione di una chiave di debug ti consente di ricevere un report invariato di un evento di azione o di origine insieme ai report generati dall'API Attribution Reporting. Puoi utilizzare le chiavi di debug per confrontare i report e trovare i 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 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 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 ad tech potrebbe voler attribuire l'acquisto al primo clic anziché al clic di ricoinvolgimento.
  2. Utilizzare i filtri per perfezionare i dati nei report a livello di evento
    • I filtri di conversione possono essere impostati in modo da ignorare gli attivatori selezionati ed escluderli dai report sugli eventi. Poiché esistono limiti al numero di attivatori per origine attribuzione, i filtri ti consentono di includere solo gli attivatori che forniscono le informazioni più utili nei report sugli eventi.
    • I filtri possono essere utilizzati anche per escludere in modo selettivo alcuni attivatori, ignorandoli di fatto. Ad esempio, se hai una campagna che ha come target le installazioni di app, ti consigliamo di escludere l'attribuzione degli attivatori post-installazione alle origini di quella 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 del filtro e 1234 è il valore. Qualsiasi attivatore con una chiave di filtro "product" che ha un valore diverso da "1234" viene ignorato.
  3. Priorità dell'origine e dell'attivatore personalizzate
    • Se a un attivatore possono essere associate più origini di attribuzione o se a un'origine possono essere attribuiti più attivatori, puoi utilizzare un numero intero a 64 bit firmato per dare la priorità ad alcuni attributi di origine/attivatore rispetto ad altri.

Collaborazione con MMP e altri

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

Utilizzare la misurazione cross-platform

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