Questa pagina è stata tradotta dall'API Cloud Translation.

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

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

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

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

Registra le origini e gli attivatori con il sistema operativo Android

L'attribuzione tra app e web sarà disponibile solo se l'API Attribution Reporting è attivata sia nel browser sia nel sistema operativo Android sullo stesso dispositivo. La disponibilità dell'API Attribution Reporting per 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 sono disponibili entrambi, le tecnologie pubblicitarie avranno la possibilità di registrare le origini web e gli attivatori web con il browser o il sistema operativo.

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

Per le campagne solo web, le tecnologie pubblicitarie possono comunque registrare sia le sorgenti sia gli attivatori 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 l'attivatore possono verificarsi in un WebView, le tecnologie pubblicitarie devono delegare sia le registrazioni dell'origine sia quelle dell'attivatore al OS. Per ulteriori informazioni, consulta la sezione sulle WebView.
I fornitori di tecnologie pubblicitarie devono evitare di registrare origini e attivatori 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 un'origine è registrata con il browser, ma l'attivatore è registrato con il sistema operativo, non è possibile abbinare i due elementi e viceversa.
Per le origini che possono generare un attivatore web o per app, è vivamente consigliato per la tecnologia pubblicitaria delegare le registrazioni delle origini web e degli attivatori all'API Attribution Reporting per Android.
Per gli attivatori che potrebbero essere stati attivati da origini basate su app, l'ad tech può scegliere di delegare la registrazione degli attivatori web all'API Attribution Reporting per Android.
Per le campagne in cui sia l'origine sia l'attivatore si verificano in un'app, entrambi dovranno essere registrati nell'API Attribution Reporting per il sistema operativo.

Registra un'origine app e un attivatore web

Per alcune campagne, l'origine può verificarsi in un'app, mentre l'attivatore 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 per prenotare. L'ad tech che pubblica l'annuncio nell'app di notizie registra l'origine del clic con l'API Attribution Reporting per Android. L'utente viene indirizzato alla pagina web dell'inserzionista in Chrome, dove può effettuare la conversione. La tecnologia pubblicitaria sul sito dell'inserzionista controlla se l'API a livello di sistema operativo è disponibile e lo è. La tecnologia pubblicitaria registra l'attivatore delle conversioni 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 associare l'origine dell'app e l'attivatore web e di inviare i report pertinenti.

Registrazione dell'origine app:

L'SDK ad tech nell'app Android del Daily News registra il clic utilizzando registerSource()
L'API Attribution Reporting su Android invia una richiesta all'URL del server ad tech fornito a registerSource()
Il server ad tech risponde con l'intestazione Attribution-Reporting-Register-Source per completare la registrazione della sorgente

Registrazione dell'attivatore web:

La tecnologia pubblicitaria registra un attivatore e controlla la disponibilità del sistema operativo nell'API Attribution Reporting
L'ARA web restituisce informazioni sulla piattaforma supportata
L'intestazione OS-Trigger indica all'API ARA web di chiamare la funzione registerWebTrigger() dell'API ARA OS
La chiamata a registerWebTrigger() avviene sotto il cofano e lo sviluppatore non deve chiamare registerWebTrigger() direttamente con il sistema operativo
L'ARA del sistema operativo prende il controllo e invia una richiesta all'URL del server ad tech fornito dall'intestazione Attribution-Reporting-Register-OS-Trigger
L'ad tech completerà la registrazione dell'attivatore con l'API OS
L'ARA OS eseguirà l'attribuzione in base alla stessa logica applicata all'attribuzione app<>app e invierà gli stessi report

Flusso di lavoro

I passaggi riportati di seguito includono ulteriori dettagli su come completare l'attività:

La tecnologia pubblicitaria dell'app registra una sorgente con l'API Attribution Reporting di Android con le seguenti modifiche:
- 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",
    ...
}
```
Nota: per le campagne che possono generare conversioni in una destinazione web OPPURE in un'app, consulta la sezione sulle destinazioni doppie
- Alcuni inserzionisti potrebbero utilizzare più fornitori di servizi di misurazione (ad esempio, un strumento di misurazione o di analisi di terze parti) con 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 allo stesso tempo il percorso di reindirizzamento 302 verrà eseguito in primo piano per le richieste di navigazione esistenti. Queste richieste verranno inviate allo stesso URL e potrebbero portare al conteggio doppio delle registrazioni da parte del fornitore di servizi di misurazione di terze parti. Per evitare il conteggio doppio delle registrazioni, gli esperti di tecnologia pubblicitaria possono modificare il comportamento di reindirizzamento per inviare la registrazione dell'API Attribution Reporting a un URL alternativo, ma deterministico.
- Per attivare questo comportamento, gli esperti di tecnologia pubblicitaria 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
```
  Nota: a tutti i reindirizzamenti successivi a questo intestazione verrà aggiunto .well-known all'inizio del percorso dell'URI di reindirizzamento.
- Il resto della procedura di registrazione dell'origine è la stessa di una registrazione dell'origine da app ad app standard.
Nota: se tu o l'app di pubblicazione utilizzate WebView per mostrare un annuncio in un'app per Android, consulta la sezione su WebView
.
La tecnologia pubblicitaria sul sito web dell'inserzionista registra l'attivatore chiedendo a Chrome di delegare la registrazione all'API Attribution Reporting per Android:
- Una volta che un utente completa una conversione su un sito web, la tecnologia pubblicitaria invia una richiesta per registrare l'attivatore in Chrome
  1. Una richiesta di pixel o fetch() può essere utilizzata per effettuare la richiesta di registrazione di un attivatore
  2. L'intestazione di richiesta Attribution-Reporting-Support viene restituita da Chrome alla tecnologia pubblicitaria. Se l'API è attiva sia nel browser Chrome sia nel dispositivo Android, l'intestazione restituirà os, web
```
Attribution-Reporting-Support: os, web
```
- L'ad tech deve quindi indicare a Chrome di eseguire la delega al sistema operativo utilizzando l'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 dell'API OS registerWebTrigger()
    - La chiamata a registerWebTrigger() avviene sotto il cofano, la tecnologia pubblicitaria non deve chiamare direttamente registerWebTrigger()
  3. L'API OS avvia una chiamata API secondaria all'URI ad tech 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 può essere inviata. In questo caso, la tecnologia pubblicitaria può comunque impostare una piattaforma preferita per gestire la registrazione dell'attivatore includendo l'intestazione Attribution-Reporting-Info. La chiave è preferred-platform e i valori consentiti sono os e web. Il browser utilizzerà la piattaforma preferita se disponibile e tornerà alla piattaforma web se il sistema operativo non è disponibile.
Nota: quando specifichi una piattaforma preferita, devono essere restituite sia l'intestazione Attribution-Reporting-Register-Trigger contenente le informazioni di registrazione web sia l'intestazione Attribution-Reporting-Register-OS-Trigger contenente le informazioni di registrazione del sistema operativo per garantire che la registrazione della piattaforma corretta possa essere eseguita. È necessario fornire sia le registrazioni per il sistema operativo sia quelle per il web, in modo che, se la piattaforma preferita non è disponibile, siano presenti le informazioni richieste per il metodo di riserva.
```
Attribution-Reporting-Info: preferred-platform=os
```
- Per completare la registrazione dell'attivatore, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting per 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"]}
    ],
    ...
}
```
- Il resto della registrazione dell'attivatore rimane invariato.

Registra un'origine web e un attivatore di app

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

Esempio

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

Registrazione dell'origine web:

La tecnologia pubblicitaria registra un'origine e controlla la disponibilità del sistema operativo nell'API Attribution Reporting
L'ARA web restituisce informazioni sulla piattaforma supportata
L'intestazione OS-Source indica all'API ARA web di chiamare la funzione registerWebSource() dell'API ARA OS
La chiamata a registerWebSource() avviene sotto il cofano e lo sviluppatore non deve chiamare registerWebSource() direttamente con il sistema operativo
L'ARA OS prende il controllo e invia una richiesta all'URL del server ad tech fornito dall'intestazione Attribution-Reporting-Register-OS-Source
La tecnologia pubblicitaria completerà la registrazione dell'origine con l'API OS

Registrazione dell'attivatore app:

L'SDK ad tech nell'app Android del negozio di abbigliamento registra l'attivatore con l'ARA del sistema operativo
L'API Attribution Reporting su Android invia una richiesta all'URL del server ad tech fornito a registerTrigger()
Il server ad tech risponde con l'intestazione Attribution-Reporting-Register-Trigger per completare la registrazione dell'attivatore
L'ARA OS eseguirà l'attribuzione in base alla stessa logica applicata all'attribuzione app<>app e invierà gli stessi report

Flusso di lavoro

I passaggi riportati di seguito includono ulteriori dettagli su come completare l'attività:

La tecnologia pubblicitaria sul sito web del publisher registra l'origine chiedendo a Chrome di delegare la registrazione all'API Attribution Reporting per Android:
- Per un caso d'uso da web ad app, quando registri un'origine, il parametro attribution source deve essere specificato direttamente utilizzando il tag attributionsrc o la registrazione JavaScript
- L'esempio seguente utilizza il tag attributionsrc per specificare il parametro source:
```
<img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">
```
L'intestazione di richiesta Attribution-Reporting-Support viene restituita da Chrome all'ad tech. Se l'API è attiva sia nel browser Chrome sia nel dispositivo Android, l'intestazione restituirà os, web.
```
Attribution-Reporting-Support: os, web
```
Nota: per eseguire correttamente la misurazione su app e web, l'API Attribution Reporting deve essere attivata sul sistema operativo Android.
La tecnologia pubblicitaria deve indicare a Chrome di eseguire la delega all'API a livello di sistema operativo utilizzando l'Attribution-Reporting-Register-OS-Sourceheader che:
1. Indica a Chrome di delegare la registrazione al sistema operativo
2. Chrome delega la registrazione al sistema operativo chiamando la funzione dell'API OS registerWebSource()
3. La chiamata a registerWebSource() avviene dietro le quinte, la tecnologia pubblicitaria non deve chiamare direttamente registerWebSource()
4. L'API OS avvia una chiamata API secondaria all'URI ad tech trasmesso 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, se disponibile, e passerà alla piattaforma web quando il sistema operativo non è disponibile.
Nota: quando specifichi una piattaforma preferita, devono essere restituite sia l'intestazione Attribution-Reporting-Register-Source contenente le informazioni di registrazione web sia l'intestazione Attribution-Reporting-Register-OS-Source contenente le informazioni di registrazione del sistema operativo per garantire che la registrazione della piattaforma corretta possa essere eseguita. È necessario fornire sia le registrazioni per il sistema operativo sia quelle per il web, in modo che, se la piattaforma preferita non è disponibile, siano presenti le informazioni richieste per il metodo di riserva.
```
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 per Android con l'intestazione di rispostaAttribution-Reporting-Register-Source. La risposta deve anche specificare una destinazione dell'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.
La tecnologia pubblicitaria nell'app dell'inserzionista registra un attivatore con l'API Attribution Reporting per Android:
- Per gli attivatori che si verificano nelle app, le app registrano gli attivatori con l'API Attribution Reporting per Android come di consueto.

Campagne con potenziali destinazioni sia web che per app

Configurare due destinazioni
- Alcune campagne possono essere configurate per generare conversioni nell'app o sulla 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 l'attivatore. Quando registri l'origine con il sistema operativo, nei rispettivi parametri è possibile specificare sia un'app sia una destinazione web.
- La destinazione dell'app deve trovarsi nel campo destination
- La destinazione web deve trovarsi nel campo web_destination
- Gli sviluppatori di Chrome devono tenere presente che il campo destination per l'API Attribution Reporting del sistema operativo 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"
    ...
}
```
- Nella sezione successiva sui report approssimativi viene spiegato in che modo l'utilizzo di destinazioni doppie può influire sul rumore nei report.
Utilizza i report approssimativi per ridurre il rumore nei report a livello di evento per le origini con due destinazioni:
- Se nella registrazione della sorgente sono stati specificati sia un sistema operativo (app) sia una destinazione web, per impostazione predefinita i report a livello di evento specificano se l'attivatore si è verificato in una destinazione web o in un'app. Tuttavia, per mantenere i limiti della privacy, a questi report verrà aggiunto ulteriore rumore.
- Gli esperti di tecnologia pubblicitaria possono utilizzare il campo coarse_event_report_destinations sotto l'intestazione Attribution-Reporting-Register-Source per attivare i report approssimativi e ridurre il rumore. Se un'origine con il campo coarse_event_report_destinations specificato ottiene l'attribuzione, il report risultante include sia le destinazioni web sia quelle app senza distinzione in base a dove si è verificato l'attivatore effettivo, ma con meno rumore rispetto ai report in cui è specificata la destinazione web o app.
- I report aggregati rimangono invariati.

Per le app che utilizzano le schede personalizzate di Chrome

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

Registra un'origine app e un attivatore di schede personalizzate:
- Segui le istruzioni per registrare un'origine app e un attivatore web.
Registra un'origine di schede personalizzate e un attivatore di app:
- Segui le istruzioni per registrare un'origine web e un attivatore di app.
Registra un'origine e un attivatore CCT
- Viene trattato come qualsiasi attribuzione web da sito a sito in Chrome.

Per le app che utilizzano WebView

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

Per consentire a WebView di utilizzare l'API Attribution Reporting, l'app di incorporamento deve essere configurata con le autorizzazioni corrette.
In WebView è disponibile solo l'attribuzione a livello di sistema operativo. L'attributo Attribution-Reporting-Support restituirà solo os e solo se è disponibile l' API Attribution Reporting per Android.

Nota: per eseguire l'attribuzione su Chrome e WebView, le registrazioni di origine e attivatori in Chrome dovranno essere delegate al sistema operativo, in quanto per WebView è supportata solo l'attribuzione basata sul sistema operativo.

Quando esegue la delega al sistema operativo, WebView potrebbe 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 su base WebView.

La differenza tra registerSource e registerWebSource è la fonte registrata come publisher. Con registerSource, l'app viene registrata come publisher. Un esempio di quando utilizzare registerSource è un'app del publisher 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 un WebView e il sito web visualizzato dal WebView mostra annunci. registerTrigger e registerWebTrigger si comportano in modo simile. Il grafico nell'articolo 3 descrive diversi scenari in cui uno sviluppatore di app o SDK vorrebbe configurare l'API per l'utilizzo di registerSource o registerWebSource, e registerTrigger o registerWebTrigger.

Per impostazione predefinita, WebView utilizzerà registerSource e registerWebTrigger quando invoca l'API Attribution Reporting per Android. In questo modo, le origini vengono associate all'app e gli attivatori all'origine di primo livello dell'URL in WebView quando si verifica l'attivazione.

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 dovrà essere impostato per ogni WebView avviato.
Se l'SDK ad tech avvia WebView, dovrà impostare questo comportamento predefinito.
Le app che vogliono utilizzare registerWebSource() per associare le registrazioni delle sorgenti al sito web in WebView anziché all'app devono essere aggiunte alla lista consentita delle WebApp. Compila questo modulo per inserire la tua app nella lista consentita. Lo scopo della lista consentita è attenuare le considerazioni sulla privacy relative all'ottenimento della fiducia per il contesto web.

Valore	Descrizione	Esempio di caso d'uso
APP_SOURCE_AND_WEB_TRIGGER (valore predefinito)	Consente alle app di registrare origini app (origini associate al nome del pacchetto dell'app) e attivatori web (attivatori associati all'eTLD+1) da WebView.	App che utilizzano WebView per pubblicare annunci anziché per consentire la navigazione web
WEB_SOURCE_AND_WEB_TRIGGER	Consente alle app di registrare origini web e attivatori 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 origini e attivatori 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 del componente WebView.
DISATTIVATO	Disattiva la registrazione di origine e attivatori da WebView.

Origine e attivazione delle registrazioni da WebView
Le ad tech devono rispondere alle registrazioni delle origini utilizzando l'intestazioneAttribution-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 ad tech.
- Per completare la registrazione dell'origine, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Android Attribution Reporting con l'intestazione di risposta.
```
 Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}
```
Il resto della registrazione dell'origine rimane invariato.
Le ad tech devono rispondere alle registrazioni degli attivatori utilizzando l'intestazioneAttribution-Reporting-Register-OS-Trigger. In base al comportamento impostato per WebView, verrà chiamato registerTrigger() o registerWebTrigger() con il sistema operativo e verrà avviata una chiamata API secondaria da Rb all'URI ad tech.
Per completare la registrazione dell'attivatore, l'endpoint dell'ad tech deve rispondere alla richiesta dell'API Attribution Reporting per 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"]}
    ],
    ...
}

Il resto della procedura di registrazione dell'attivatore rimane invariato.

Debug

Quando configuri un'app per l'implementazione web, ti consigliamo di configurare i report di debug per verificare se le origini e gli attivatori vengono registrati correttamente e, se non lo sono, per ricevere informazioni sul motivo.

Per la procedura di debug generale dei report sull'attribuzione, consulta la guida di riferimento per il debug.