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 trigger che si verificano sullo stesso dispositivo. Browser come Chrome può delegare le registrazioni di origine e di attivazione ad Attribution Reporting API per Android anziché gestire queste registrazioni nel browser. In questo modo Android può abbinare fonti e attivatori su siti e app.

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

Quando imposti l'attribuzione cross-app e web, ti consigliamo vivamente di Acquisisci familiarità con le soluzioni di debug disponibili per assicurarti che il tuo che la configurazione funzioni come previsto.

Registra origini e trigger con il sistema operativo Android

L'attribuzione cross-app e web sarà disponibile solo se l'attribuzione L'API di reporting sia abilitata sia nel browser sia nel sistema operativo Android dispositivo. Viene inviata la disponibilità dell'API Android Attribution Reporting tramite l'intestazione Attribution-Reporting-Support. Questa intestazione restituirà i sistemi operativi, web o entrambe, a seconda delle opzioni disponibili sul dispositivo. Se entrambi sono disponibili, i tecnici pubblicitari avranno quindi la possibilità di registrare le fonti web e con il browser o il sistema operativo.

Il team ad tech deve decidere se registrare l'origine web o l'attivatore web con il browser o il sistema operativo.

  • Per le campagne solo per il web, i tecnici pubblicitari possono comunque registrare sia le sorgenti che gli attivatori con l'API Attribution Reporting di Chrome o scegliere di delegare entrambe le soluzioni al sistema operativo. Per le campagne solo web in cui l'origine o l'attivatore può verificarsi in un WebView, le ad tech devono delegare sia le registrazioni di origine sia quelle di trigger a il sistema operativo. Per ulteriori informazioni, consulta la sezione relativa ai componenti WebView.
  • I tecnici pubblicitari dovrebbero evitare di registrare origini e trigger sia con Chrome e le API Android contemporaneamente per evitare di creare attribuzioni duplicate report.
  • L'attribuzione avviene separatamente per i browser e il sistema operativo. Se una fonte è registrato nel browser, ma il trigger è registrato nel sistema operativo, questi due non possono essere abbinati e viceversa.
  • Per le origini che possono generare un attivatore di app o web, è molto consigliata alla tecnologia pubblicitaria di delegare la sorgente web e attivare le registrazioni per l'API Android Attribution Reporting.
  • Per gli attivatori potenzialmente generati da origini basate su app, la tecnologia pubblicitaria può scegli di delegare la registrazione degli attivatori web ad Android Attribution Reporting tramite Google Cloud CLI o tramite l'API Compute Engine.
  • Per le campagne in cui sia l'origine che l'attivatore si verificano in un'app, devono essere registrati con l'API Attribution Reporting del sistema operativo.

Registra un'origine app e un trigger web

Per alcune campagne, l'origine potrebbe trovarsi in un'app mentre si verifica l'attivatore 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 che vende voli per Parigi e fare clic per prenotare. La tecnologia pubblicitaria che pubblica l'annuncio registra la sorgente dei clic con l'API Android Attribution Reporting. L'utente viene indirizzato alla pagina web dell'inserzionista in Chrome, dove può convertire. La tecnologia pubblicitaria sul sito dell'inserzionista controlla se l'API a livello di sistema operativo è disponibile. La tecnologia pubblicitaria registra l'attivatore di conversione tramite indicare a Chrome di delegare la registrazione al sistema operativo anziché eseguire la registrazione direttamente con l'API Attribution Reporting di Chrome. L'attribuzione a livello di sistema operativo L'API di reporting è quindi in grado di abbinare l'origine app e l'attivatore 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 Daily News per Android registra il clic utilizzando registerSource()

  2. L'API Attribution Reporting su Android invia una richiesta al server ad tech URL fornito a registerSource()

  3. Il server ad tech risponde con Attribution-Reporting-Registration-Source per completare la registrazione di origine

Registrazione trigger web:

  1. L'ad tech registra un attivatore e verifica la disponibilità del sistema operativo nel API Attribution Reporting

  2. L'ARA web restituisce informazioni sulla piattaforma supportata

  3. L'intestazione OS-Trigger indica all'API web ARA di chiamare l'API OS ARA Funzione registerWebTrigger()

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

  5. L'ARA del sistema operativo prende in carico e invia una richiesta all'URL del server ad tech fornito intestazione Attribution-Reporting-Register-OS-Trigger

  6. L'ad tech completerà la registrazione dell'attivatore con l'API del sistema operativo

  7. L'ARA del sistema operativo eseguirà l'attribuzione in base alla stessa logica applicata l'attribuzione dell'app<>e inviare 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 Attribution di Android l'API di reporting con le seguenti modifiche:

    • Per registrare l'origine di un'app che dovrebbe generare una conversione su un sito web, il parametro L'intestazione della risposta Attribution-Reporting-Register-Source deve includere un link web (eTLD+1) anziché una destinazione dell'app.
    di Gemini Advanced. 
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
    • Alcuni inserzionisti potrebbero utilizzare più fornitori di servizi di misurazione, ad esempio uno strumento di misurazione di terze parti o 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 in nello stesso momento in cui il percorso di reindirizzamento 302 viene eseguito in primo piano per richieste di navigazione. Queste richieste arriveranno allo stesso URL e potrebbero del fornitore di servizi di misurazione di terze parti, il doppio conteggio delle registrazioni. A impedire il doppio conteggio delle registrazioni, i tecnici pubblicitari possono modificare il comportamento di reindirizzamento di inviare la registrazione dell'API Attribution Reporting a un'alternativa URL deterministico.

    • Per consentire questo comportamento, i tecnici pubblicitari devono includere una nuova intestazione HTTP quando rispondere a una richiesta di registrazione:

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

    • Il resto della procedura di registrazione dell'origine è uguale alla procedura standard registrazione da app a app.

    di Gemini Advanced.

  2. La tecnologia pubblicitaria sul sito web dell'inserzionista registra l'attivatore chiedendo Chrome per delegare la registrazione all'API Android Attribution Reporting:

    • Quando un utente completa una conversione su un sito web, l'ad tech effettua una richiedi di registrare il trigger con Chrome

      1. È possibile utilizzare una richiesta di pixel o fetch() per farla registrare attivare

      2. Chrome restituisce l'intestazione della richiesta Attribution-Reporting-Support alla tecnologia pubblicitaria. Se l'API è abilitata sia sul browser Chrome sia sulla Dispositivo Android, l'intestazione restituirà os, web

      Attribution-Reporting-Support: os, web

    • La tecnologia pubblicitaria deve quindi indicare a Chrome di delegare il sistema operativo al sistema operativo utilizzando Intestazione Attribution-Reporting-Register-OS-Trigger che:

      1. Comunica 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 dietro le quinte, la tecnologia pubblicitaria non deve chiamare direttamente registerWebTrigger()

      3. L'API del sistema operativo avvia una chiamata API secondaria all'URI della tecnologia pubblicitaria trasmesso 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 possono essere inviati. In questi casi, la tecnologia pubblicitaria può comunque impostare un per gestire la registrazione trigger includendo Intestazione Attribution-Reporting-Info. La chiave è la piattaforma preferita i valori consentiti sono os e web. Il browser utilizzerà la piattaforma preferita. quando disponibile e ripiega sulla piattaforma web quando il sistema operativo non disponibile.

    di Gemini Advanced. 
    Attribution-Reporting-Info: preferred-platform=os
    • Per completare la registrazione dell'attivatore, l'endpoint della tecnologia pubblicitaria deve rispondere alla richiesta dell'API Android Attribution Reporting 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 trigger dell'app

Per alcune campagne, una sorgente può essere presente su un sito in un browser mobile mentre l'attivatore avviene in un'app sullo stesso dispositivo.

Esempio

Un utente sta navigando su un sito nel browser Chrome di uno smartphone Android. Vedono un annuncio relativo a un maglione in uno dei loro negozi preferiti. Fanno clic un annuncio e vengono indirizzati all'app che hanno già scaricato. La tecnologia pubblicitaria sul il sito web in cui è stato pubblicato l'annuncio registra la sorgente dei clic indicando a Chrome delegare la registrazione all'API Android Attribution Reporting anziché utilizzando l'API Attribution Reporting su Chrome. L'utente acquista il maglione in l'app per gli acquisti. La tecnologia pubblicitaria nell'app dell'inserzionista registra quindi l'attivatore di conversione con l'API Android Attribution Reporting. A livello di sistema operativo L'API Attribution Reporting è in grado di abbinare l'origine web e l'attivatore dell'app e e inviare i report pertinenti.

Flusso di attribuzione dal web ad app
Flusso di attribuzione da web ad app

Registrazione origine web:

  1. L'ad tech registra un'origine e verifica la disponibilità del sistema operativo nel API Attribution Reporting

  2. L'ARA web restituisce informazioni sulla piattaforma supportata

  3. L'intestazione OS-Source indica all'API web ARA di chiamare l'API OS ARA Funzione registerWebSource()

  4. La chiamata a registerWebSource() avviene in background e lo sviluppatore lo fa. non è necessario chiamare registerWebSource() direttamente dal sistema operativo

  5. L'ARA del sistema operativo prende in carico e invia una richiesta all'URL del server ad tech fornito dall'intestazione Attribution-Reporting-Register-OS-Source

  6. L'ad tech completerà la registrazione del codice sorgente con l'API del sistema operativo

Registrazione dell'attivatore dell'app:

  1. L'SDK ad tech nell'app Android del negozio di abbigliamento registra l'attivatore con l'ARA dell'OS

  2. L'API Attribution Reporting su Android invia una richiesta al server ad tech URL fornito a registerTrigger()

  3. Il server ad tech risponde con il Attribution-Reporting-Register-Trigger per completare la registrazione del trigger

  4. L'ARA del sistema operativo eseguirà l'attribuzione in base alla stessa logica applicata l'attribuzione dell'app<>e inviare 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 la fonte indicando Chrome per delegare la registrazione all'API Android Attribution Reporting:

    • Per un caso d'uso da web ad app, quando registri una sorgente, l'attribuzione deve essere specificato direttamente utilizzando il parametro Tag attributionsrc o utilizzando la registrazione JavaScript
    • Nell'esempio seguente viene utilizzato il tag attributionsrc per specificare il valore parametro source:
    <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 al ad tech. Se l'API è abilitata sia sul 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 l'API a livello di sistema operativo utilizzando Intestazione Attribution-Reporting-Register-OS-Source che:

    1. Comunica 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 dietro le quinte, la tecnologia pubblicitaria non è necessario chiamare registerWebSource() direttamente
    4. L'API del sistema operativo avvia una chiamata API secondaria all'URI della tecnologia pubblicitaria trasmesso da il browser
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • In alcuni casi, l'intestazione Attribution-Reporting-Support non è disponibile. In questi casi, la tecnologia pubblicitaria può comunque impostare una piattaforma preferita da gestire la registrazione di origine includendo l'intestazione Attribution-Reporting-Info. La chiave è la piattaforma preferita e i valori consentiti sono os e web. La utilizzerà la piattaforma preferita quando sarà disponibile e ricorrerà sulla piattaforma web quando il sistema operativo non è disponibile.
    di Gemini Advanced. 
    Attribution-Reporting-Info: preferred-platform=os
    • Per completare la registrazione dell'origine, l'endpoint della tecnologia pubblicitaria deve rispondere alla richiesta dell'API Android Attribution Reporting con l'intestazione della risposta Attribution-Reporting-Register-Source. La risposta deve anche specificare nel campo Destinazione.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Per supportare i reindirizzamenti per le registrazioni di origine, Chrome seguirà le reindirizzano e richiamano le API di contesto web per ogni hop di reindirizzamento.
    • Il resto della registrazione di origine rimane invariato.

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

    • Per gli attivatori che si verificano nelle app, le app registrano gli attivatori con l'API Android Attribution Reporting come di consueto.

Campagne con potenziali destinazioni sia per le app che per il web

  1. Configurare due destinazioni

    • Alcune campagne possono essere configurate per la conversione nell'app dell'inserzionista o sulla pagina web dell'inserzionista in base a vari fattori, ad esempio se l'utente in cui l'app sia installata.
    • In questi casi, si consiglia di delegare la registrazione di origine al sistema operativo dove disponibile, in modo che l'origine possa essere attribuita correttamente da dove si verifica l'attivatore. Quando registri l'origine con il sistema operativo, viene eseguita l'app e la destinazione web possono essere specificate nei rispettivi parametri.
    • La destinazione dell'app deve essere nel campo destination
    • La destinazione web deve essere nel campo web_destination
    • Gli sviluppatori di Chrome devono tenere presente che il campo destination per il sistema operativo L'API Attribution Reporting deve essere un pacchetto di 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 prossima sezione sui report approssimativi spiegherà come usare la doppia destinazione. potrebbe influire sul rumore nei report.

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

    • Se nell'origine sono stati specificati sia un sistema operativo (app) sia una destinazione web registrazione, i report a livello di evento specificano se il trigger in una destinazione web o app per impostazione predefinita. Tuttavia, per mantenere limiti di privacy, a questi report verrà aggiunto ulteriore rumore.
    • I tecnici pubblicitari possono utilizzare il campo coarse_event_report_destinations sotto Intestazione Attribution-Reporting-Register-Source per attivare i report approssimativi e ridurre il rumore. Se una fonte con coarse_event_report_destinations il campo specificato vince l'attribuzione, il report risultante include sia l'app e le destinazioni web senza distinzione in merito a dove l'attivatore ma con meno rumore rispetto ai report in cui l'app o la destinazione web è specificato.
    • I report aggregati rimangono invariati.

Per le app che utilizzano schede personalizzate di Chrome

Alcune app potrebbero utilizzare schede personalizzate per eseguire il rendering dei contenuti web. Il comportamento delle schede personalizzate in modo simile a una normale pagina web quando effettui misurazioni su app e siti web mobile.

  1. Registra un'origine app e un attivatore Scheda personalizzata:
  2. Registra un'origine di Scheda personalizzata e un attivatore dell'app:
  3. Registra un'origine CCT e un trigger CCT

Per le app che utilizzano WebView

Alcune app potrebbero utilizzare WebView per visualizzare contenuti. Esistono diversi casi d'uso per WebView, ad esempio rendering degli annunci, hosting di contenuti web o app personalizzate funzioni più adatte a un formato web.

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

  2. Quando delega al sistema operativo, WebView può usare registerSource o registerWebSource e registerTrigger o registerWebTrigger. Quali sono i metodi usata da WebView viene impostata tramite il rendering dell'app WebView e viene determinata in per WebView.

    • La differenza tra registerSource e registerWebSource è che viene registrata come publisher. Con registerSource, l'app viene registrata in qualità di publisher; un esempio di quando usare registerSource potrebbe essere un app del publisher che mostra un annuncio il cui rendering viene eseguito utilizzando WebView. Con registerWebSource, il sito web ospitato in WebView viene registrato come editore; un esempio di quando usare registerWebSource è un'app che ospita un componente WebView, mentre il sito web che viene visualizzato pubblicare annunci. registerTrigger e registerWebTrigger si comportano in modo simile. La Il grafico nell'elemento 3 descrive in dettaglio scenari diversi di quando uno sviluppatore di app o di SDK configurare l'API in modo che usi registerSource o registerWebSource, e registerTrigger o registerWebTrigger.

  3. Per impostazione predefinita, WebView utilizzerà registerSource e registerWebTrigger quando chiamata l'API Android Attribution Reporting. In questo modo le origini vengono associate l'app e si attiva con l'origine di primo livello dell'URL in WebView quando l'attivatore si verifica.

    • Se un'app richiede un comportamento diverso, dovrà usare un nuovo metodo setAttributionRegistrationBehavior su androidx.webkit.WebViewSettingsCompat . Questo metodo consente di specificare se WebView deve chiamare registerWebSource() o registerWebTrigger() anziché registerSource() o registerTrigger().
      • Questo comportamento dovrà essere impostato per ogni componente WebView avviato.
      • Se l'SDK ad tech avvia WebView, l'SDK dovrà impostare questo comportamento predefinito.
      • Per le app che vogliono utilizzare registerWebSource() per associare l'origine registrazioni con il sito web in WebView anziché nell'app, devono entrare a far parte della lista consentita di WebApp. Compila questo modulo per entrare nella lista consentita. La l'intento della lista consentita è ridurre le considerazioni sulla privacy stabilire la fiducia per il contesto web.
    • Opzioni per setAttributionRegistrationBehavior
    Valore Descrizione Esempio di caso d'uso
    APP_SOURCE_AND_WEB_TRIGGER (predefinita) Consente alle app di registrare da WebView origini app (sorgenti associate al nome del pacchetto dell'app) e trigger web (attivatori associati all'eTLD+1). App che utilizzano WebView per pubblicare annunci anziché attivare la navigazione sul web
    WEB_SOURCE_AND_WEB_TRIGGER Consente alle app di registrare origini web e trigger web da WebView. App browser basate su WebView, in cui le impressioni degli annunci e le conversioni potrebbero verificarsi sui siti web in WebView.
    APP_SOURCE_AND_APP_TRIGGER Consente alle app di registrare le origini e gli attivatori delle app da WebView. App basate su WebView in cui le impressioni degli annunci e le conversioni devono sempre essere associate all'app anziché all'eTLD+1 di WebView.
    DISATTIVATO Disattiva l'origine e attiva la registrazione da WebView.

  4. Recuperare e attivare le registrazioni da WebView

    • I tecnici pubblicitari devono rispondere alle registrazioni di origine utilizzando Intestazione Attribution-Reporting-Register-OS-Source. In base al comportamento impostato per WebView, verrà chiamato registerSource() o registerWebSource() con il sistema operativo e avvia una chiamata API secondaria da Android Attribution l'API di reporting all'URI della tecnologia pubblicitaria.

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

    • Il resto della registrazione di origine rimane invariato.

  5. I tecnici pubblicitari devono rispondere in modo da attivare le registrazioni utilizzando Intestazione Attribution-Reporting-Register-OS-Trigger. In base al comportamento impostato per WebView, verrà chiamato registerTrigger() o registerWebTrigger() con il sistema operativo e avvia una chiamata API secondaria da Rb all'URI della tecnologia pubblicitaria.

    • Per completare la registrazione dell'attivatore, l'endpoint della tecnologia pubblicitaria deve rispondere alla richiesta dell'API Android Attribution Reporting con la risposta intestazione.
    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, è consigliabile configurare il debug per verificare se le origini e gli attivatori vengono registrati correttamente e non sono registrati per ricevere informazioni sul motivo.

Per la procedura generale di debug di Attribution Reporting, consulta il libro di ricette sul debug.