Esta página foi traduzida pela API Cloud Translation.

Guia de implementação da API Attribution Reporting em apps e na Web

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.

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ção registerWebTrigger()
A chamada para registerWebTrigger() acontece em segundo plano, e o desenvolvedor não precisa chamar registerWebTrigger() 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",
    ...
}
```
Observação :para campanhas que podem gerar conversões em uma campanha OU um destino de app, consulte a seção sobre destinos duplos
.
- 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
```
  Observação: todos os redirecionamentos subsequentes após esse cabeçalho terá .well-known anexado ao início do caminho do URI de redirecionamento.
- O restante do processo de registro da fonte é igual ao de um processo o registro de origem entre apps.
.
Observação: se você ou o app de publicação estiverem usando o WebView para mostrar um anúncio nativo em um app Android, consulte a seção sobre WebView
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
  1. Um pixel ou solicitação fetch() pode ser usado para fazer a solicitação para registrar um acionar
  2. O 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 retornar os, 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:
  1. Instrui o Chrome a delegar o registro ao SO.
  2. 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 chamar registerWebTrigger() diretamente
  3. 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çalho Attribution-Reporting-Info. A chave é a plataforma preferencial os valores permitidos são os e web. O navegador usará a plataforma de preferência quando disponível, e eles voltam para a plataforma da Web quando o SO é indisponível.
.
Observação: os Attribution-Reporting-Register-Trigger cabeçalho contendo as informações de registro da web e o Cabeçalho Attribution-Reporting-Register-OS-Trigger contendo o registro do SO devem ser retornadas ao especificar uma plataforma preferencial para garantir registro na plataforma. Os registros do SO e da Web precisam ser fornecido, para que, se a plataforma preferida não estiver disponível, as informações necessária para o método substituto.
```
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 — Fluxo de atribuição da Web para app

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ção registerWebSource()
A chamada para registerWebSource() acontece em segundo plano e o desenvolvedor Não é necessário chamar registerWebSource() com o SO diretamente
A 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 acionador
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 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">
```
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 retornar os, web.
```
Attribution-Reporting-Support: os, web
```
Observação :a API Attribution Reporting precisa estar ativada no SO Android para fazer medições em apps e na 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:
1. Instrui o Chrome a delegar o registro ao SO.
2. O Chrome delega o registro ao SO chamando a função da API do SO registerWebSource()
3. A chamada para registerWebSource() acontece em segundo plano, a adtech faz não precisa chamar registerWebSource() diretamente
4. 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çalho Attribution-Reporting-Info. A chave é a plataforma preferencial e os valores permitidos são os e web. 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.
.
Observação: os Attribution-Reporting-Register-Source cabeçalho contendo as informações de registro da web e o Cabeçalho Attribution-Reporting-Register-OS-Source contendo o registro do SO devem ser retornadas ao especificar uma plataforma preferencial para garantir registro na plataforma. Os registros do SO e da Web precisam ser fornecido, para que, se a plataforma preferida não estiver disponível, as informações necessária para o método substituto.
```
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çalho Attribution-Reporting-Register-Source para ativar os relatórios gerais e reduzir o ruído. Se uma origem com coarse_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.

Observação: para fazer atribuições no Chrome e na WebView, registros de fonte e acionador no Chrome precisarão ser delegados ao SO já que somente a atribuição baseada em SO é compatível com a WebView.
Ao delegar ao SO, a WebView pode usar registerSource ou registerWebSource e registerTrigger ou registerWebTrigger. Quais métodos são usado pela WebView é definido pelo app que renderiza a WebView e é determinado por WebView.
- A diferença entre registerSource e registerWebSource é qual origem é registrada como o editor. Com registerSource, o app é registrado como editor, um exemplo de quando usar registerSource seria uma app do editor que mostra um anúncio renderizado usando a WebView. Com registerWebSource, o site hospedado na WebView será registrado como o editora Um exemplo de quando usar registerWebSource seria um app que hospeda uma WebView, e o site renderizado pela WebView não é mostrando anúncios. registerTrigger e registerWebTrigger 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 usar registerSource ou registerWebSource, e registerTrigger ou registerWebTrigger.

Por padrão, a WebView vai usar registerSource e registerWebTrigger 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(). ou registerWebTrigger(), em vez de registerSource() ou registerTrigger().
- 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.

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 chamar registerSource() ou registerWebSource() 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 chamar registerTrigger() ou registerWebTrigger() 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).