Guida all'implementazione tra web e app dell'API Attribution Reporting

L'API Attribution Reporting consente l'attribuzione cross-app e web per le origini e i trigger che si verificano sullo stesso dispositivo. I browser, come Chrome, possono delegare la registrazione di origine e trigger all'API Attribution Reporting per Android anziché gestirle nel browser. In questo modo, Android può abbinare origini e trigger su siti e app.

Questa guida ti insegnerà a configurare l'attribuzione cross-app e cross-web.

Quando configuri l'attribuzione cross-app e cross-web, ti consigliamo vivamente di acquisire familiarità anche con le soluzioni di debug disponibili per verificare che la configurazione funzioni come previsto.

Registrare origini e trigger con il sistema operativo Android

L'attribuzione cross-app e web sarà disponibile solo se l'API Attribution Reporting è attivata sia nel browser che nel sistema operativo Android sullo stesso dispositivo. La disponibilità dell'API Attribution Reporting di Android viene inviata tramite l'intestazione Attribution-Reporting-Support. Questa intestazione restituirà os, web o entrambi, a seconda di ciò che è disponibile sul dispositivo. Se entrambi sono disponibili, le tecnologie pubblicitarie potranno scegliere di registrare le origini web e i trigger web con il browser o il sistema operativo.

La tecnologia pubblicitaria deve decidere se registrare l'origine web o il trigger web con il browser o il sistema operativo.

  • Per le campagne solo web, le tecnologie pubblicitarie possono comunque registrare sia le origini che i trigger con l'API Attribution Reporting di Chrome o scegliere di delegare entrambi al sistema operativo. Per le campagne solo web in cui l'origine o il trigger possono verificarsi in una WebView, le tecnologie pubblicitarie devono delegare le registrazioni dell'origine e del trigger al sistema operativo. Per saperne di più, consulta la sezione sulle WebView.

  • I fornitori di tecnologie pubblicitarie devono evitare di registrare origini e trigger contemporaneamente con le API Chrome e Android per evitare di creare report sull'attribuzione duplicati.

  • L'attribuzione avviene separatamente per i browser e il sistema operativo. Se una sorgente è registrata con il browser, ma il trigger è registrato con il sistema operativo, i due non possono essere abbinati e viceversa.

  • Per le origini che potrebbero generare un trigger app o web, è vivamente consigliato che la tecnologia pubblicitaria deleghi le registrazioni di origini e trigger web all'API Attribution Reporting di Android.

  • Per i trigger che potrebbero essere stati generati da origini basate su app, la tecnologia pubblicitaria può scegliere di delegare la registrazione dei trigger web all'API Attribution Reporting di Android.

  • Per le campagne in cui sia l'origine che il trigger si verificano in un'app, entrambi dovranno essere registrati con l'API Attribution Reporting del sistema operativo.

Registrare un'origine app e un attivatore web

Per alcune campagne, l'origine può verificarsi in un'app, mentre l'attivazione si verifica su un sito web nel browser mobile sullo stesso dispositivo.

Esempio

Un utente sta leggendo articoli nella sua app di notizie preferita. Vede un annuncio di voli economici per Parigi e fa clic con entusiasmo per prenotare. La tecnologia pubblicitaria che pubblica l'annuncio nell'app di notizie registra l'origine del clic con l'API Attribution Reporting di Android. L'utente viene indirizzato alla pagina web dell'inserzionista in Chrome, dove può effettuare la conversione. La tecnologia pubblicitaria sul sito dell'inserzionista verifica se l'API a livello di sistema operativo è disponibile e lo è. La tecnologia pubblicitaria registra il trigger di conversione chiedendo a Chrome di delegare la registrazione al sistema operativo anziché registrarla direttamente con l'API Attribution Reporting di Chrome. L'API Attribution Reporting a livello di sistema operativo è quindi in grado di abbinare l'origine dell'app e il trigger web e inviare i report pertinenti.

Flusso di attribuzione da app a web
Flusso di attribuzione da app a web

Registrazione dell'origine dell'app:

  1. L'SDK ad tech nell'app Android Daily News registra il clic utilizzando registerSource()

  2. L'API Attribution Reporting su Android invia una richiesta all'URL del server di tecnologia pubblicitaria fornito a registerSource()

  3. Il server di tecnologia pubblicitaria risponde con l'intestazione Attribution-Reporting-Register-Source per completare la registrazione dell'origine

Registrazione del trigger web:

  1. La tecnologia pubblicitaria registra un trigger e verifica la disponibilità del sistema operativo nell'API Attribution Reporting

  2. L'ARA web restituisce informazioni sulla piattaforma supportata

  3. L'intestazione OS-Trigger indica all'API web ARA di chiamare la funzione registerWebTrigger() dell'API ARA del sistema operativo

  4. La chiamata a registerWebTrigger() avviene in background e lo sviluppatore non deve chiamare registerWebTrigger() direttamente con il sistema operativo

  5. L'OS ARA prende il controllo e invia una richiesta all'URL del server di tecnologia pubblicitaria fornito dall'intestazione Attribution-Reporting-Register-OS-Trigger.

  6. La tecnologia pubblicitaria completerà la registrazione del trigger con l'API del sistema operativo

  7. L'OS ARA eseguirà l'attribuzione in base alla stessa logica applicata all'attribuzione app<>app e invierà gli stessi report

Flusso di lavoro

I seguenti passaggi includono ulteriori dettagli su come completare l'attività:

  1. La tecnologia pubblicitaria dell'app registra una sorgente con l'API Attribution Reporting di Android con i seguenti aggiustamenti:

    • Per registrare un'origine app che dovrebbe generare conversioni su un sito web, l'intestazione della risposta Attribution-Reporting-Register-Source deve includere una destinazione web (eTLD+1) anziché una destinazione app.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
    • Alcuni inserzionisti potrebbero utilizzare più fornitori di misurazione (ad esempio, uno strumento di misurazione di terze parti o uno strumento di analisi) utilizzando catene di reindirizzamento 302. In alcuni casi, l'API Attribution Reporting seguirà il percorso di reindirizzamento specificato nell'intestazione Attribution-Reporting-Redirect in background e contemporaneamente il percorso di reindirizzamento 302 viene eseguito in primo piano per le richieste di navigazione esistenti. Queste richieste verranno inviate allo stesso URL e potrebbero comportare il doppio conteggio delle registrazioni da parte del fornitore di misurazione di terze parti. Per evitare il conteggio doppio delle registrazioni, le tecnologie pubblicitarie possono modificare il comportamento di reindirizzamento per inviare la registrazione dell'API Attribution Reporting a un URL alternativo ma deterministico.

    • Per attivare questo comportamento, le tecnologie pubblicitarie devono includere una nuova intestazione HTTP quando rispondono a una richiesta di registrazione:

      • L'intestazione è Attribution-Reporting-Redirect-Config
      • Il valore dell'intestazione deve essere redirect-302-to-well-known
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • Il resto della procedura di registrazione dell'origine è identico a una registrazione dell'origine standard da app ad app.

  2. La tecnologia pubblicitaria sul sito web dell'inserzionista registra il trigger chiedendo a Chrome di delegare la registrazione all'API Attribution Reporting di Android:

    • Una volta che un utente completa una conversione su un sito web, la tecnologia pubblicitaria invia una richiesta per registrare il trigger con Chrome

      1. Una richiesta di pixel o fetch() può essere utilizzata per richiedere la registrazione di un trigger

      2. L'intestazione della richiesta Attribution-Reporting-Support viene restituita da Chrome alla tecnologia pubblicitaria. Se l'API è abilitata sia nel browser Chrome sia sul dispositivo Android, l'intestazione restituirà os, web

      Attribution-Reporting-Support: os, web

    • La tecnologia pubblicitaria deve quindi indicare a Chrome di delegare al sistema operativo l'utilizzo dell'intestazione Attribution-Reporting-Register-OS-Trigger, che:

      1. Indica a Chrome di delegare la registrazione al sistema operativo

      2. Chrome delega la registrazione al sistema operativo chiamando la funzione API del sistema operativo registerWebTrigger()

        • La chiamata a registerWebTrigger() avviene in background, la tecnologia pubblicitaria non deve chiamare direttamente registerWebTrigger()

      3. L'API del sistema operativo avvia una chiamata API secondaria all'URI della tecnologia pubblicitaria passato dal browser

      Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"

    • In alcuni casi, l'intestazione Attribution-Reporting-Support non è disponibile e non può essere inviata. In questo caso, la tecnologia pubblicitaria può comunque impostare una piattaforma preferita per gestire la registrazione dei trigger includendo l'intestazione Attribution-Reporting-Info. La chiave è preferred-platform e i valori consentiti sono os e web. Il browser utilizzerà la piattaforma preferita quando disponibile e tornerà alla piattaforma web quando il sistema operativo non è disponibile.

    Attribution-Reporting-Info: preferred-platform=os
    • Per completare la registrazione del trigger, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting di Android utilizzando l'intestazione della risposta.
    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

Registra un'origine web e un attivatore di app

Per alcune campagne, una sorgente può verificarsi su un sito in un browser mobile, mentre il trigger si verifica in un'app sullo stesso dispositivo.

Esempio

Un utente sta navigando su un sito nel browser Chrome sul suo smartphone Android. Visualizza un annuncio di un maglione di uno dei suoi negozi preferiti. Fanno clic sull'annuncio e vengono reindirizzati all'app che hanno già scaricato. La tecnologia pubblicitaria sul sito web in cui è stato pubblicato l'annuncio registra l'origine del clic chiedendo a Chrome di delegare la registrazione all'API Attribution Reporting di Android anziché utilizzare l'API Attribution Reporting su Chrome. L'utente acquista il maglione nell'app di shopping. La tecnologia pubblicitaria nell'app dell'inserzionista registra quindi il trigger di conversione con l'API Attribution Reporting di Android. L'API Attribution Reporting a livello di sistema operativo è in grado di abbinare l'origine web e il trigger dell'app e inviare i report pertinenti.

Flusso di attribuzione web-to-app
Flusso di attribuzione da web ad app

Registrazione della fonte web:

  1. La tecnologia pubblicitaria registra una sorgente e verifica la disponibilità del sistema operativo nell'API Attribution Reporting

  2. L'ARA web restituisce informazioni sulla piattaforma supportata

  3. L'intestazione OS-Source indica all'API web ARA di chiamare la funzione registerWebSource() dell'API ARA del sistema operativo

  4. La chiamata a registerWebSource() avviene in background e lo sviluppatore non deve chiamare registerWebSource() direttamente con il sistema operativo

  5. L'OS ARA prende il controllo e invia una richiesta all'URL del server di tecnologia pubblicitaria fornito dall'intestazione Attribution-Reporting-Register-OS-Source

  6. La tecnologia pubblicitaria completerà la registrazione dell'origine con l'API OS

Registrazione del trigger dell'app:

  1. L'SDK di tecnologia pubblicitaria nell'app per Android del negozio di abbigliamento registra il trigger con l'API ARA del sistema operativo

  2. L'API Attribution Reporting su Android invia una richiesta all'URL del server di tecnologia pubblicitaria fornito a registerTrigger()

  3. Il server della tecnologia pubblicitaria risponde con l'intestazione Attribution-Reporting-Register-Trigger per completare la registrazione del trigger.

  4. L'OS ARA eseguirà l'attribuzione in base alla stessa logica applicata all'attribuzione app<>app e invierà gli stessi report

Flusso di lavoro

I seguenti passaggi includono ulteriori dettagli su come completare l'attività:

  1. La tecnologia pubblicitaria sul sito web del publisher registra l'origine chiedendo a Chrome di delegare la registrazione all'API Attribution Reporting di Android:

    • Per un caso d'uso da web ad app, durante la registrazione di una sorgente, il parametro sorgente di attribuzione deve essere specificato direttamente, utilizzando il tag attributionsrc o la registrazione JavaScript.
    • L'esempio seguente utilizza il tag attributionsrc per specificare il parametro sorgente:
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. L'intestazione della richiesta Attribution-Reporting-Support viene restituita da Chrome alla tecnologia pubblicitaria. Se l'API è abilitata sia nel browser Chrome sia sul dispositivo Android, l'intestazione restituirà os, web.

    Attribution-Reporting-Support: os, web

  3. La tecnologia pubblicitaria deve indicare a Chrome di delegare all'API a livello di sistema operativo utilizzando l'intestazione Attribution-Reporting-Register-OS-Source che:

    1. Indica a Chrome di delegare la registrazione al sistema operativo
    2. Chrome delega la registrazione al sistema operativo chiamando la funzione API del sistema operativo registerWebSource()
    3. La chiamata a registerWebSource() avviene in background, la tecnologia pubblicitaria non deve chiamare registerWebSource() direttamente
    4. L'API del sistema operativo avvia una chiamata API secondaria all'URI della tecnologia pubblicitaria passato dal browser
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • In alcuni casi, l'intestazione Attribution-Reporting-Support non è disponibile. In questo caso, la tecnologia pubblicitaria può comunque impostare una piattaforma preferita per gestire la registrazione dell'origine includendo l'intestazione Attribution-Reporting-Info. La chiave è preferred-platform e i valori consentiti sono os e web. Il browser utilizzerà la piattaforma preferita quando disponibile e tornerà alla piattaforma web quando il sistema operativo non è disponibile.
    Attribution-Reporting-Info: preferred-platform=os
    • Per completare la registrazione dell'origine, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting di Android con l'intestazione della risposta Attribution-Reporting-Register-Source. La risposta deve specificare anche una destinazione app nel campo di destinazione.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Per supportare i reindirizzamenti per le registrazioni delle origini, Chrome seguirà i reindirizzamenti e chiamerà le API di contesto web per ogni hop di reindirizzamento.
    • Il resto della registrazione dell'origine rimane invariato.

  4. La tecnologia pubblicitaria nell'app dell'inserzionista registra un trigger con l'API Attribution Reporting di Android:

    • Per i trigger che si verificano nelle app, queste registrano i trigger con l'API Attribution Reporting di Android come di consueto.

Campagne con potenziali destinazioni web e per app

  1. Configurare le doppie destinazioni

    • Alcune campagne possono essere configurate per la conversione nell'app dell'inserzionista o nella pagina web dell'inserzionista a seconda di vari fattori, ad esempio se l'utente ha installato l'app.
    • In questi casi, è consigliabile delegare la registrazione dell'origine al sistema operativo, se disponibile, in modo che l'origine possa essere attribuita correttamente indipendentemente da dove si verifica il trigger. Quando registri l'origine con il sistema operativo, puoi specificare una destinazione app e web nei rispettivi parametri.
    • La destinazione dell'app deve essere nel campo destination
    • La destinazione web deve trovarsi nel campo web_destination
    • Gli sviluppatori di Chrome devono notare che il campo destination per l'API Attribution Reporting del sistema operativo deve essere un pacchetto dell'app e non un URL.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
    • La sezione successiva sui report approssimativi spiega in che modo l'utilizzo di due destinazioni potrebbe influire sul rumore nei report.

  2. Utilizza i report approssimativi per ridurre il rumore nei report a livello di evento per le origini con doppia destinazione:

    • Se nella registrazione dell'origine sono state specificate sia una destinazione OS (app) sia una destinazione web, i report a livello di evento specificano per impostazione predefinita se l'attivazione è avvenuta in una destinazione web o in una destinazione app. Tuttavia, per mantenere i limiti di privacy, a questi report verrà aggiunto rumore aggiuntivo.
    • Le tecnologie pubblicitarie possono utilizzare il campo coarse_event_report_destinations nell'intestazione Attribution-Reporting-Register-Source per attivare i report approssimativi e ridurre il rumore. Se una sorgente con il campo coarse_event_report_destinations specificato vince l'attribuzione, il report risultante include sia le destinazioni app che web senza distinzione tra la posizione in cui si è verificato l'attivatore effettivo, ma con meno rumore rispetto ai report in cui è specificata la destinazione app o web.
    • I report aggregati rimangono invariati.

Per le app che utilizzano le schede personalizzate di Chrome

Alcune app potrebbero utilizzare le schede personalizzate per il rendering dei contenuti web. Le schede personalizzate si comportano in modo simile a una normale pagina web durante la misurazione su app e siti web mobile.

  1. Registra un'origine app e un attivatore di schede personalizzate:

  2. Registra un'origine scheda personalizzata e un attivatore di app:

  3. Registra un'origine CCT e un trigger CCT

Per le app che utilizzano WebView

Alcune app potrebbero utilizzare WebView per visualizzare i contenuti. Esistono vari casi d'uso per WebView, ad esempio il rendering di annunci, l'hosting di contenuti web o funzionalità personalizzate delle app più adatte a un formato web.

  1. Per consentire alle WebView di utilizzare l'API Attribution Reporting, l'app di incorporamento deve essere configurata con le autorizzazioni corrette.

  2. In WebView è disponibile solo l'attribuzione a livello di sistema operativo. L'intestazione Attribution-Reporting-Support restituirà solo il sistema operativo e solo se l'API Attribution Reporting di Android è disponibile.

  3. Quando delega al sistema operativo, WebView può utilizzare registerSource o registerWebSource e registerTrigger o registerWebTrigger. I metodi utilizzati da WebView vengono impostati dall'app che esegue il rendering di WebView e vengono determinati in base a ogni WebView.

    • La differenza tra registerSource e registerWebSource è la sorgente registrata come publisher. Con registerSource, l'app viene registrata come editore. Un esempio di quando utilizzare registerSource è un'app editore che mostra un annuncio visualizzato utilizzando WebView. Con registerWebSource, il sito web ospitato in WebView viene registrato come publisher. Un esempio di quando utilizzare registerWebSource è un'app che ospita una WebView e il sito web di cui viene eseguito il rendering da WebView mostra gli annunci. registerTrigger e registerWebTrigger si comportano in modo simile. Il grafico nel punto 3 descrive diversi scenari in cui uno sviluppatore di app o SDK potrebbe voler configurare l'API per utilizzare registerSource o registerWebSource, e registerTrigger o registerWebTrigger.
    • Per impostazione predefinita, WebView utilizzerà registerSource e registerWebTrigger quando chiama l'API Attribution Reporting di Android. In questo modo, le origini vengono associate all'app e i trigger all'origine di primo livello dell'URL nella WebView quando si verifica il trigger.

      • Se un'app richiede un comportamento diverso, dovrà utilizzare un nuovo metodo setAttributionRegistrationBehavior nella classe androidx.webkit.WebViewSettingsCompat. Questo metodo specifica se WebView deve chiamare registerWebSource() o registerWebTrigger() anziché registerSource() o registerTrigger().

      • Questo comportamento deve essere impostato per ogni WebView avviata.

      • Se l'SDK di tecnologia pubblicitaria avvia WebView, deve impostare questo comportamento predefinito.

      • Per le app che vogliono utilizzare registerWebSource() per associare le registrazioni delle sorgenti al sito web in WebView anziché all'app, devono entrare nella lista consentita delle app web. Compila questo modulo per entrare nella lista consentita. Lo scopo della lista consentita è di mitigare le considerazioni sulla privacy relative all'instaurazione della fiducia per il contesto web.

      Valore Descrizione Caso d'uso di esempio
      APP_SOURCE_AND_WEB_TRIGGER (valore predefinito) Consente alle app di registrare origini app (origini associate al nome del pacchetto dell'app) e trigger web (trigger associati all'eTLD+1) da WebView. App che utilizzano WebView per pubblicare annunci anziché attivare la navigazione web
      WEB_SOURCE_AND_WEB_TRIGGER Consente alle app di registrare fonti web e trigger web da WebView. App browser basate su WebView, in cui le impressioni e le conversioni degli annunci potrebbero verificarsi entrambe sui siti web in WebView.
      APP_SOURCE_AND_APP_TRIGGER Consente alle app di registrare origini e trigger delle app da WebView. App basate su WebView in cui le impressioni e le conversioni degli annunci devono sempre essere associate all'app anziché all'eTLD+1 di WebView.
      DISATTIVATO Disattiva la registrazione di origini e trigger da WebView.
    1. Registrare fonti e trigger da WebView

    2. Le tecnologie pubblicitarie devono rispondere alle registrazioni delle origini utilizzando l'intestazione Attribution-Reporting-Register-OS-Source. In base al comportamento impostato per WebView, verrà chiamato registerSource() o registerWebSource() con il sistema operativo e verrà avviata una chiamata API secondaria dall'API Android Attribution Reporting all'URI della tecnologia pubblicitaria.

      • Per completare la registrazione dell'origine, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting di Android con l'intestazione della risposta.
       Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. Il resto della registrazione dell'origine rimane invariato.

    4. Le ad tech devono rispondere alle registrazioni dei trigger utilizzando l'intestazione Attribution-Reporting-Register-OS-Trigger. In base al comportamento impostato per WebView, verrà chiamata registerTrigger() o registerWebTrigger() con il sistema operativo e verrà avviata una chiamata API secondaria da Rb all'URI della tecnologia pubblicitaria.

    5. Per completare la registrazione del trigger, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting di Android con l'intestazione della risposta.

    Attribution-Reporting-Register-OS-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

Debug

Quando configuri un'implementazione da app a web, ti consigliamo di configurare i report di debug per verificare se le origini e i trigger vengono registrati correttamente e, in caso contrario, per ricevere informazioni sul motivo.

Per i passaggi generali di debug dei report sull'attribuzione, consulta il manuale di debug.