A API Attribution Reporting permite a atribuição entre apps e na Web para fontes e gatilhos que ocorrem no mesmo dispositivo. Navegadores como o Chrome, pode delegar registros de acionador e fonte aos relatórios de atribuição API para Android em vez de processar esses registros no navegador. Isso permite que o Android faça a correspondência de origens e acionadores em sites e apps.
Neste guia, você vai aprender a configurar a atribuição entre apps e na Web.
Ao configurar a atribuição entre apps e na Web, é altamente recomendável também familiarize-se com as soluções de depuração disponíveis para garantir que está funcionando conforme o esperado.
Registrar origens e gatilhos com o SO Android
A atribuição entre apps e na Web só estará disponível se a atribuição A API Reporting está ativada no navegador e no SO Android da mesma forma dispositivo. A disponibilidade da API Attribution Reporting do Android é enviada por meio do cabeçalho Attribution-Reporting-Support. Esse cabeçalho retornará os, Web ou de ambos os tipos, dependendo do que estiver disponível no dispositivo. Se ambos forem disponíveis, as adtechs vão ter a opção de registrar fontes e sites é acionada com o navegador ou o sistema operacional.
A adtech precisa decidir se quer registrar a fonte ou o acionador da Web no navegador ou no sistema operacional.
- Em campanhas somente para a Web, as adtechs ainda podem registrar fontes e acionadores com a API Attribution Reporting do Chrome ou delegar os dois ao SO. Para campanhas somente para a Web em que a origem ou o acionador podem acontecer em uma WebView, as adtechs precisam delegar os registros do acionador e da fonte aos do SO. Consulte a seção sobre WebViews para mais informações.
- As adtechs precisam evitar o registro de fontes e acionadores com o Chrome. e APIs do Android simultaneamente para evitar a criação de atribuições duplicadas e detecção de ameaças.
- A atribuição ocorre separadamente para navegadores e SO. Se uma fonte for registrados no navegador, mas o acionador estiver registrado no SO, esses dois e vice-versa.
- Para fontes que podem resultar em um app ou acionador da Web, é altamente recomendado para a adtech delegar registros da Web e acionar registros para a API Attribution Reporting do Android.
- Para acionadores que podem ter sido acionados por fontes baseadas em apps, a adtech pode optar por delegar o registro do acionador da Web ao Relatório de Atribuição do Android. API.
- Para campanhas em que a origem e o acionador acontecem em um aplicativo, ambos serão precisam estar registrados na API Attribution Reporting do SO.
Registrar uma origem do app e um gatilho da Web
Para algumas campanhas, a origem pode ocorrer em um app, enquanto o acionador ocorre em um site usando um navegador para dispositivos móveis no mesmo aparelho.
Exemplo
Um usuário está lendo artigos no app de notícias favorito dele. Ele vê um anúncio de preços baratos. de voos para Paris e clique para reservar. A adtech que veicula o anúncio de notícias registra a origem do clique com a API Attribution Reporting do Android. O usuário é direcionado para a página da Web do anunciante no Chrome, onde pode converter. A adtech no site do anunciante verifica se a API no nível do SO é disponível, e está. A adtech registra o acionador de conversão instruindo o Chrome a delegar o registro ao SO em vez de registrar diretamente com a API Attribution Reporting do Chrome. A atribuição no nível do SO A API Reporting pode, então, fazer a correspondência entre a origem do aplicativo e o acionador da Web e enviar nos relatórios relevantes.
![Fluxo de atribuição de app para Web](https://developers.google.cn/static/privacy-sandbox/private-advertising/attribution-reporting/cross-web-app/a2w_diagram.png?hl=pt-br)
Registro da origem do app:
O SDK de adtechs no app Daily News para Android registra o clique usando
registerSource()
A API Attribution Reporting no Android envia uma solicitação ao servidor de adtechs URL fornecido para
registerSource()
O servidor da adtech responde com "Attribution-Reporting-Register-Source" cabeçalho para concluir o registro da origem
Registro do acionador da Web:
A adtech registra um acionador e verifica a disponibilidade do SO no API Attribution Reporting
A ARA da Web retorna informações sobre qual plataforma é compatível
O cabeçalho
OS-Trigger
instrui a API ARA da Web a chamar a API OS ARA FunçãoregisterWebTrigger()
A chamada para
registerWebTrigger()
acontece em segundo plano, e o desenvolvedor não precisa chamarregisterWebTrigger()
diretamente com o SO;A ARA da SO assume o controle e envia uma solicitação ao URL do servidor de adtechs fornecido por o cabeçalho
Attribution-Reporting-Register-OS-Trigger
;A adtech vai concluir o registro do acionador com a API do SO
A ARA do SO realizará a atribuição de acordo com a mesma lógica aplicada atribuição de app<>app e enviar os mesmos relatórios
Fluxo de trabalho
As etapas abaixo incluem mais detalhes sobre como concluir a tarefa:
A adtech do app registra uma fonte com a Atribuição do Android. API Reporting com os seguintes ajustes:
- Para registrar uma origem de app que precisa ser convertida em um site, o
O cabeçalho de resposta
Attribution-Reporting-Register-Source
precisa incluir um valor da Web (eTLD+1) em vez de um destino de app.
.Attribution-Reporting-Register-Source: { "web_destination": "https://advertiser.example", ... }
- Alguns anunciantes podem usar vários provedores de medição (por exemplo, uma ferramenta de medição de terceiros ou de análise) usando cadeias de redirecionamento 302. Em alguns casos, a API Attribution Reporting vai seguir o caminho de redirecionamento especificado no cabeçalho Attribution-Reporting-Redirect em segundo plano e em ao mesmo tempo em que o caminho de redirecionamento 302 é executado em primeiro plano para solicitações de navegação. Essas solicitações vão para o mesmo URL e podem resultar no provedor de medição terceirizado com registros de contagem dupla. Para evitar a contagem duplicada de registros, as adtechs podem modificar o comportamento de redirecionamento para enviar o registro da API Attribution Reporting a uma origem um URL determinístico.
Para ativar esse comportamento, as adtechs precisam incluir um novo cabeçalho HTTP ao responder a uma solicitação de registro:
- O cabeçalho é
Attribution-Reporting-Redirect-Config
- O valor do cabeçalho deve ser "redirect-302-to-well-known".
"Attribution-Reporting-Redirect-Config": "redirect-302-to-well-known"
- O cabeçalho é
O restante do processo de registro da fonte é igual ao de um processo o registro de origem entre apps.
- Para registrar uma origem de app que precisa ser convertida em um site, o
O cabeçalho de resposta
A adtech no site do anunciante registra o acionador pedindo: O Chrome delega o registro à API Attribution Reporting do Android:
Quando um usuário conclui uma conversão em um site, a adtech faz uma solicitação para registrar o acionador no Chrome
Um pixel ou solicitação
fetch()
pode ser usado para fazer a solicitação para registrar um acionarO cabeçalho da solicitação
Attribution-Reporting-Support
é retornado pelo Chrome. à adtech. Se a API estiver ativada no navegador Chrome e na um dispositivo Android, o cabeçalho vai retornaros, web
.
"Attribution-Reporting-Support": "os, web"
A adtech informará ao Chrome para delegar ao SO usando o Cabeçalho
Attribution-Reporting-Register-OS-Trigger
, que:Instrui o Chrome a delegar o registro ao SO.
O Chrome delega o registro ao SO chamando a função da API do SO
registerWebTrigger()
- A chamada para
registerWebTrigger()
acontece em segundo plano, a adtech não precisa chamarregisterWebTrigger()
diretamente
- A chamada para
A API do SO inicia uma chamada de API secundária para o URI da adtech transmitido do navegador
"Attribution-Reporting-Register-OS-Trigger": "https://adtech.example/register-trigger", "https://other-adtech.example/register-trigger"
Em alguns casos, o cabeçalho
Attribution-Reporting-Support
não está disponível, e não pode ser enviado. Quando isso acontece, a adtech ainda pode definir uma para processar o registro dos acionadores incluindo o CabeçalhoAttribution-Reporting-Info
. A chave é a plataforma preferencial os valores permitidos sãoos
eweb
. O navegador usará a plataforma de preferência quando disponível, e eles voltam para a plataforma da Web quando o SO é indisponível.
Attribution-Reporting-Info: preferred-platform=os
- Para concluir o registro do acionador, o endpoint da adtech precisa responder à solicitação da API Attribution Reporting do Android usando o cabeçalho de resposta.
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"]} ], ... }
- O restante do registro do acionador continua o mesmo.
Registrar uma fonte da Web e um acionador de app
Para algumas campanhas, uma origem pode ocorrer em um site em um navegador para dispositivos móveis, enquanto o acionador ocorre em um app no mesmo dispositivo.
Exemplo
Um usuário está navegando em um site no navegador Chrome usando um smartphone Android. Ele vê um anúncio de um suéter de uma das lojas favoritas dele. Ele clica no botão e são levados ao app que já fizeram o download. A adtech no o site em que o anúncio foi veiculado registra a origem do clique instruindo o Chrome delegar o registro para a API Attribution Reporting do Android em vez de usando a API Attribution Reporting no Chrome. O usuário compra o suéter do app de compras. A adtech no app do anunciante registra o de conversão com a API Attribution Reporting do Android. Nível do SO A API Attribution Reporting pode fazer a correspondência entre a fonte da Web e o acionador do app, e enviar os relatórios relevantes.
![Fluxo de atribuição da Web para o app](https://developers.google.cn/static/privacy-sandbox/private-advertising/attribution-reporting/cross-web-app/w2a_diagram.png?hl=pt-br)
Registro de fonte da Web:
A adtech registra uma fonte e verifica a disponibilidade do SO no API Attribution Reporting
A ARA da Web retorna informações sobre qual plataforma é compatível
O cabeçalho
OS-Source
instrui a API ARA da Web a chamar a API OS ARA FunçãoregisterWebSource()
A chamada para
registerWebSource()
acontece em segundo plano e o desenvolvedor Não é necessário chamarregisterWebSource()
com o SO diretamenteA ARA da SO assume o controle e envia uma solicitação ao URL do servidor de adtechs fornecido pelo cabeçalho
Attribution-Reporting-Register-OS-Source
A adtech vai concluir o registro da origem com a API do SO.
Registro do acionador de app:
O SDK de adtech no app Android da loja de roupas registra o acionador com a ARA do SO
A API Attribution Reporting no Android envia uma solicitação ao servidor de adtechs URL fornecido para
registerTrigger()
O servidor da adtech responde com
Attribution-Reporting-Register-Trigger
. cabeçalho para concluir o registro do acionadorA ARA do SO realizará a atribuição de acordo com a mesma lógica aplicada atribuição de app<>app e enviar os mesmos relatórios
Fluxo de trabalho
As etapas abaixo incluem mais detalhes sobre como concluir a tarefa:
A adtech no site do editor registra a fonte ao instruir O Chrome delegar o registro para a API Attribution Reporting do Android:
- Em um caso de uso da Web para um app, ao registrar uma fonte, a atribuição
source deve ser especificado diretamente, usando o parâmetro
Tag
attributionsrc
ou usando o registro JavaScript - O exemplo a seguir usa a tag
attributionsrc
para especificar o source parâmetro:
<img src="https://adtech.example/conversionpixel" attributionsrc="https://adtech.example/register-source?purchase=12">
- Em um caso de uso da Web para um app, ao registrar uma fonte, a atribuição
source deve ser especificado diretamente, usando o parâmetro
Tag
O cabeçalho da solicitação
Attribution-Reporting-Support
é retornado pelo Chrome à ad tech. Se a API estiver ativada no navegador Chrome e no dispositivo Android, o cabeçalho vai retornaros, web
."Attribution-Reporting-Support": "os, web"
A adtech vai dizer ao Chrome para delegar à API no nível do SO usando o Cabeçalho
Attribution-Reporting-Register-OS-Source
, que:- Instrui o Chrome a delegar o registro ao SO.
- O Chrome delega o registro ao SO chamando a função da API do SO
registerWebSource()
- A chamada para
registerWebSource()
acontece em segundo plano, a adtech faz não precisa chamarregisterWebSource()
diretamente - A API do SO inicia uma chamada de API secundária para o URI da adtech transmitido da o navegador
"Attribution-Reporting-Register-OS-Source": "https://adtech.example/register-source"
- Em alguns casos, o cabeçalho
Attribution-Reporting-Support
não está disponível. Quando isso acontece, a adtech ainda pode definir uma plataforma preferencial para lidar com o registro da origem incluindo o cabeçalhoAttribution-Reporting-Info
. A chave é a plataforma preferencial e os valores permitidos sãoos
eweb
. A navegador da Web vai usar a plataforma preferida quando disponível e vai substituí-la por na plataforma da Web quando o SO está indisponível.
Attribution-Reporting-Info: preferred-platform=os
- Para concluir o registro da fonte, o endpoint da adtech precisa responder
à solicitação da API Attribution Reporting do Android com o cabeçalho de resposta
Attribution-Reporting-Register-Source
: A resposta também deve especificar uma app no campo de destino.
Attribution-Reporting-Register-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
- Para oferecer suporte a redirecionamentos para registros de fonte, o Chrome seguirá o e chamar as APIs de contexto da Web para cada salto de redirecionamento.
- O restante do registro da fonte permanece o mesmo.
A adtech no app do anunciante registra um acionador com o API Attribution Reporting:
- Para gatilhos que ocorrem em apps, os apps registram acionadores com o a API Attribution Reporting do Android normalmente.
Campanhas que têm destinos em potencial para apps e Web
Configurar destinos duplos
- Algumas campanhas podem ser configuradas para conversão no app do anunciante ou na página da Web do anunciante, dependendo de vários fatores, como se o usuário tem o app instalado.
- Nesses casos, é recomendado delegar o registro da origem ao SO, quando disponível para que a origem possa ser atribuída corretamente, independentemente de onde o acionador ocorre. Ao registrar a origem no SO, um o destino da Web e do app podem ser especificados nos respectivos parâmetros.
- O destino do app precisa estar no campo
destination
- O destino da Web precisa estar no campo
web_destination
- Os desenvolvedores do Chrome precisam observar que o campo
destination
do SO A API Attribution Reporting precisa ser um pacote de apps, e não um URL.
Attribution-Reporting-Register-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", "web_destination": "https://example.advertiser" ... }
- A próxima seção sobre relatórios aproximados explicará como o uso de destinos duplos pode afetar o ruído nos seus relatórios.
Use a geração de relatórios brutos para reduzir o ruído em relatórios de eventos origens de destino:
- Se um SO (app) e um destino da Web foram especificados na origem registro, os relatórios de eventos vão especificar se o acionador aconteceu em um destino da Web ou de app por padrão. No entanto, para manter limites de privacidade, mais ruído será adicionado a esses relatórios.
- As adtechs podem usar o campo
coarse_event_report_destinations
no CabeçalhoAttribution-Reporting-Register-Source
para ativar os relatórios gerais e reduzir o ruído. Se uma origem comcoarse_event_report_destinations
campo especificado ganha a atribuição, o relatório resultante inclui o app e destinos da Web sem distinção de onde o gatilho ocorreu, mas com menos ruído do que os relatórios em que o aplicativo ou destino é especificado. - Os relatórios agregados permanecem inalterados.
Para apps que usam guias personalizadas do Chrome
Alguns apps podem usar guias personalizadas para renderizar conteúdo da Web. As guias personalizadas se comportam de forma semelhante a uma página da Web normal ao avaliar apps e sites para dispositivos móveis.
- Registre uma origem de app e um acionador de guia personalizada:
- Siga as instruções para registrar uma origem do app e um acionador da Web.
- Registre uma origem de guia personalizada e um acionador de app:
- Siga as instruções para registrar uma fonte da Web e um acionador de app.
- Registrar uma origem e um acionador de CCT
- Isso é tratado da mesma forma que qualquer atribuição site a site no Chrome.
Para apps que usam a WebView
Alguns apps podem usar o WebView para mostrar conteúdo. Há vários casos de uso para WebView, como renderização de anúncios, hospedagem de conteúdo da Web ou personalização de apps recursos mais adequados para um formato da Web.
Apenas a atribuição no nível do SO está disponível na WebView. A O cabeçalho Attribution-Reporting-Support retornará apenas os e somente se o A API Attribution Reporting para Android está disponível.
Ao delegar ao SO, a WebView pode usar
registerSource
ouregisterWebSource
eregisterTrigger
ouregisterWebTrigger
. Quais métodos são usado pela WebView é definido pelo app que renderiza a WebView e é determinado por WebView.- A diferença entre
registerSource
eregisterWebSource
é qual origem é registrada como o editor. ComregisterSource
, o app é registrado como editor, um exemplo de quando usarregisterSource
seria uma app do editor que mostra um anúncio renderizado usando a WebView. ComregisterWebSource
, o site hospedado na WebView será registrado como o editora Um exemplo de quando usarregisterWebSource
seria um app que hospeda uma WebView, e o site renderizado pela WebView não é mostrando anúncios.registerTrigger
eregisterWebTrigger
se comportam de maneira semelhante. A o gráfico no item 3 detalha diferentes cenários em que um desenvolvedor de app ou SDK é melhor configurar a API para usarregisterSource
ouregisterWebSource
, eregisterTrigger
ouregisterWebTrigger
.
- A diferença entre
Por padrão, a WebView vai usar
registerSource
eregisterWebTrigger
quando chamando a API Attribution Reporting do Android. Isso associa origens o app e acionado com a origem de nível superior do URL no WebView quando o gatilho ocorre.- Se um app exigir um comportamento diferente, ele vai precisar usar um novo método
setAttributionRegistrationBehavior no androidx.webkit.WebViewSettingsCompat
. Esse método especifica se a WebView precisa chamar
registerWebSource()
. ouregisterWebTrigger()
, em vez deregisterSource()
ouregisterTrigger()
.- Esse comportamento precisará ser definido para cada WebView iniciado.
- Se o SDK da adtech estiver iniciando o WebView, ele precisará definir esse comportamento padrão.
- Para apps que gostariam de usar
registerWebSource()
para associar a origem registros no site em WebView em vez de no aplicativo, eles devem entrar na lista de permissões do WebApp. Preencha este formulário para participar da lista de permissões. A da lista de permissões é reduzir as considerações de privacidade sobre Como estabelecer a confiança no contexto da Web.
- Opções para setAttributionRegistrationBehavior
Valor Descrição Exemplo de caso de uso APP_SOURCE_AND_WEB_TRIGGER (padrão) Permite que os apps registrem fontes associadas ao nome do pacote do app e acionadores da Web (acionadores associados ao eTLD+1) da WebView. Apps que usam a WebView para veicular anúncios em vez de ativar a navegação na Web. WEB_SOURCE_AND_WEB_TRIGGER Permite que os apps registrem fontes e acionadores da Web da WebView. Apps de navegador baseados em WebView, em que as impressões e conversões de anúncios podem acontecer em sites na WebView. APP_SOURCE_AND_APP_TRIGGER Permite que os apps registrem fontes e acionadores de apps da WebView. Apps baseados em WebView em que as impressões e conversões de anúncios precisam ser sempre associadas ao app em vez do eTLD+1 da WebView. DESATIVADO Desativa o registro de fonte e acionador da WebView. - Se um app exigir um comportamento diferente, ele vai precisar usar um novo método
setAttributionRegistrationBehavior no androidx.webkit.WebViewSettingsCompat
. Esse método especifica se a WebView precisa chamar
Registros de fonte e acionador da WebView
As adtechs precisam responder aos registros de fonte usando o Cabeçalho
Attribution-Reporting-Register-OS-Source
. Com base no comportamento definido para a WebView, isso vai chamarregisterSource()
ouregisterWebSource()
com o SO e iniciar uma chamada de API secundária no ambiente de atribuição API Reporting ao URI da adtech.- Para concluir o registro da fonte, o endpoint da adtech precisa: responda à solicitação da API Attribution Reporting do Android com o no cabeçalho da resposta.
Attribution-Reporting-Register-OS-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
O restante do registro da fonte permanece o mesmo.
As adtechs precisam responder aos registros de acionador usando o Cabeçalho
Attribution-Reporting-Register-OS-Trigger
. Com base no comportamento definido para a WebView, isso vai chamarregisterTrigger()
ouregisterWebTrigger()
com o SO e inicie uma chamada de API secundária de Rb para o URI da adtech.- Para concluir o registro do acionador, o endpoint da adtech precisa: responda à solicitação da API Attribution Reporting do Android com a resposta cabeçalho.
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"]} ], ... }
- O restante do processo de registro do acionador continua o mesmo.
Depurar
Ao configurar uma implementação de app para a Web, é recomendável configurar a depuração. para verificar se as origens e os acionadores estão sendo registrados corretamente e se não estão registrados, para receber informações sobre o motivo.
Para ver as etapas gerais de depuração da API Attribution Reporting, consulte o manual de depuração (link em inglês).