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 da Web para fontes e acionadores que ocorrem no mesmo dispositivo. Navegadores, como o Chrome, podem delegar os registros de origem e acionador para a API Attribution Reporting para Android em vez de processar esses registros no navegador. Isso permite que o Android combine fontes e acionadores em sites e apps.

Este guia ensina como configurar a atribuição entre apps e na Web.

Ao configurar a atribuição entre apps e da Web, é altamente recomendável se familiarizar com as soluções de depuração disponíveis para garantir que a configuração esteja funcionando como esperado.

Registrar origens e acionadores com o SO Android

A atribuição entre apps e da Web só vai estar disponível se a API Attribution Reporting estiver ativada no navegador e no SO Android no mesmo dispositivo. A disponibilidade da API Attribution Reporting do Android é enviada pelo cabeçalho "Attribution-Reporting-Support". Esse cabeçalho vai retornar o SO, a Web ou ambos, dependendo do que estiver disponível no dispositivo. Se ambos estiverem disponíveis, as adtechs poderão registrar origens e acionadores da Web com o navegador ou o SO.

A adtech precisa decidir se vai registrar a origem ou o acionador da Web com o navegador ou o SO.

Para campanhas somente na 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 na Web em que a origem ou o acionador podem acontecer em uma WebView, as adtechs precisam delegar os registros de origem e acionador ao sistema operacional. Consulte a seção sobre WebViews para mais informações.
As adtechs precisam evitar o registro de origens e acionadores com as APIs do Chrome e do Android simultaneamente para evitar a criação de relatórios de atribuição duplicados.
A atribuição acontece separadamente para navegadores e SOs. Se uma origem for registrada no navegador, mas o acionador for registrado no SO, os dois não poderão ser combinados e vice-versa.
Para fontes que podem resultar em um acionador do app ou da Web, é altamente recomendado que a adtech delegue os registros de origem e acionador da Web para a API Attribution Reporting do Android.
Para acionadores que podem ter sido impulsionados por origens baseadas em apps, a adtech pode delegar o registro do acionador da Web à API Attribution Reporting do Android.
Para campanhas em que a origem e o acionador acontecem em um app, ambos precisam ser registrados na API Attribution Reporting do SO.

Registrar uma fonte de app e um acionador da Web

Em algumas campanhas, a origem pode ocorrer em um app, enquanto o acionador ocorre em um site no navegador móvel no mesmo dispositivo.

Exemplo

Um usuário está lendo artigos no app de notícias favorito. Ele vê um anúncio de voos baratos para Paris e clica para reservar. A adtech que veicula o anúncio no app de notícias registra a origem do clique com a API Attribution Reporting do Android. O usuário é direcionado à 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 está disponível, e ela está. A adtech registra o acionador de conversão instruindo o Chrome a delegar o registro ao SO em vez de registrá-lo diretamente com a API Attribution Reporting do Chrome. A API Attribution Reporting no nível do SO pode corresponder à origem do app e ao acionador da Web e enviar os relatórios relevantes.

Registro da origem do app:

O SDK de adtech no app Android do Daily News registra o clique usando registerSource()
A API Attribution Reporting no Android envia uma solicitação para o URL do servidor de adtech fornecido para registerSource()
O servidor de adtech responde com o cabeçalho Attribution-Reporting-Register-Source para concluir o registro da origem.

Registro de acionador da Web:

A adtech registra um acionador e verifica a disponibilidade do SO na API Attribution Reporting.
O ARA da Web retorna informações sobre qual plataforma é compatível
O cabeçalho OS-Trigger informa à API ARA da Web para chamar a função registerWebTrigger() da API ARA do SO.
A chamada para registerWebTrigger() acontece em segundo plano, e o desenvolvedor não precisa chamar registerWebTrigger() diretamente com o SO.
O OS ARA assume o controle e envia uma solicitação para o URL do servidor de adtech fornecido pelo cabeçalho Attribution-Reporting-Register-OS-Trigger.
A adtech vai concluir o registro do acionador com a API do SO.
O ARA do SO vai 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 a seguir incluem mais detalhes sobre como concluir a tarefa:

A adtech do app registra uma fonte com a API Attribution Reporting do Android com os seguintes ajustes:
- Para registrar uma origem de app que deve ser convertida em um site, o cabeçalho de resposta Attribution-Reporting-Register-Source precisa incluir um destino da Web (eTLD+1) em vez de um destino do app.
```
Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
```
Observação: para campanhas que podem converter em um destino da Web OU em um 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 ou de análise de terceiros) com 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, ao mesmo tempo, o caminho de redirecionamento 302 será executado em primeiro plano para solicitações de navegação existentes. Essas solicitações vão para o mesmo URL e podem resultar em registros duplos do provedor de medição de terceiros. Para evitar o registro duplo, as adtechs podem modificar o comportamento de redirecionamento para enviar o registro da API Attribution Reporting para um URL alternativo, mas de forma determinística.
- 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 precisa ser redirect-302-to-well-known
```
Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
```
  Observação: todos os redirecionamentos subsequentes a este cabeçalho vão ter .well-known anexado ao início do caminho do URI de redirecionamento.
- O restante do processo de registro de origem é igual ao registro de origem padrão entre apps.
Observação: se você ou o app de publicação estiver usando a WebView para mostrar um anúncio em um app Android, consulte a seção sobre WebView.
A adtech no site do anunciante registra o acionador pedindo ao Chrome para delegar o registro à API Attribution Reporting do Android:
- Depois que um usuário conclui uma conversão em um site, a adtech faz uma solicitação para registrar o acionador com o Chrome.
  1. Uma solicitação de pixel ou fetch() pode ser usada para registrar um gatilho.
  2. O cabeçalho de solicitação Attribution-Reporting-Support é retornado pelo Chrome para a adtech. Se a API estiver ativada no navegador Chrome e no dispositivo Android, o cabeçalho vai retornar os, web.
```
Attribution-Reporting-Support: os, web
```
- A adtech precisa informar ao Chrome para delegar ao SO usando o cabeçalho Attribution-Reporting-Register-OS-Trigger, que:
  1. Informa ao Chrome para 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 pelo 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 está indisponível e não pode ser enviado. Quando isso acontece, a adtech ainda pode definir uma plataforma preferencial para processar o registro do acionador incluindo o cabeçalho Attribution-Reporting-Info. A chave é preferred-platform, e os valores permitidos são os e web. O navegador vai usar a plataforma preferida quando disponível e vai voltar para a plataforma da Web quando o SO estiver indisponível.
Observação: tanto o cabeçalho Attribution-Reporting-Register-Trigger que contém as informações de registro da Web quanto o cabeçalho Attribution-Reporting-Register-OS-Trigger que contém as informações de registro do SO precisam ser retornados ao especificar uma plataforma preferencial para garantir que o registro da plataforma correta possa ocorrer. Os registros do SO e da Web precisam ser fornecidos para que, se a plataforma preferencial não estiver disponível, as informações necessárias para o método alternativo estejam presentes.
```
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 permanece o mesmo.

Registrar uma fonte da Web e um acionador do app

Em 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 no smartphone Android. Ele vê um anúncio de um suéter de uma das lojas favoritas dele. O usuário clica no anúncio e é direcionado para o app que já foi instalado. A adtech no site em que o anúncio foi veiculado registra a origem do clique instruindo o Chrome a delegar o registro à API Attribution Reporting do Android em vez de usar a API Attribution Reporting no Chrome. O usuário compra o suéter no app de compras. A adtech no app do anunciante registra o acionador de conversão com a API Attribution Reporting do Android. A API Attribution Reporting no nível do SO pode fazer a correspondência entre a fonte da Web e o acionador do app e enviar os relatórios relevantes.

Registro de origem da Web:

A adtech registra uma fonte e verifica a disponibilidade do SO na API Attribution Reporting.
O ARA da Web retorna informações sobre qual plataforma é compatível
O cabeçalho OS-Source informa à API ARA da Web para chamar a função registerWebSource() da API ARA do SO.
A chamada para registerWebSource() acontece em segundo plano, e o desenvolvedor não precisa chamar registerWebSource() diretamente com o SO.
O OS ARA assume o controle e envia uma solicitação para o URL do servidor de adtech fornecido pelo cabeçalho Attribution-Reporting-Register-OS-Source.
A adtech vai concluir o registro da origem com a API OS.

Registro do acionador do app:

O SDK de adtech no app Android da loja de roupas registra o acionador com o ARA do SO.
A API Attribution Reporting no Android envia uma solicitação para o URL do servidor de adtech fornecido a registerTrigger()
O servidor de adtech responde com o cabeçalho Attribution-Reporting-Register-Trigger para concluir o registro do acionador.
O ARA do SO vai 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 a seguir incluem mais detalhes sobre como concluir a tarefa:

A adtech no site do editor registra a origem instruindo o Chrome a delegar o registro à API Attribution Reporting do Android:
- Para um caso de uso da Web para o app, ao registrar uma origem, o parâmetro de origem da atribuição precisa ser especificado diretamente usando a tag attributionsrc ou o registro do JavaScript.
- O exemplo a seguir usa a tag attributionsrc para especificar o parâmetro de origem:
```
<img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">
```
O cabeçalho de solicitação Attribution-Reporting-Support é retornado pelo Chrome para a tecnologia de anúncios. 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 medir corretamente no app e na Web.
A adtech precisa informar ao Chrome para delegar à API no nível do SO usando o cabeçalho Attribution-Reporting-Register-OS-Source, que:
1. Informa ao Chrome para 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 não precisa chamar registerWebSource() diretamente.
4. A API do SO inicia uma chamada de API secundária para o URI da adtech transmitido pelo navegador.
```
Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
```
- Em alguns casos, o cabeçalho Attribution-Reporting-Support está indisponível. Quando isso acontece, a adtech ainda pode definir uma plataforma preferencial para processar o registro da origem incluindo o cabeçalho Attribution-Reporting-Info. A chave é preferred-platform e os valores permitidos são os e web. O navegador vai usar a plataforma preferida quando disponível e vai voltar para a plataforma da Web quando o SO estiver indisponível.
Observação: tanto o cabeçalho Attribution-Reporting-Register-Source que contém as informações de registro da Web quanto o cabeçalho Attribution-Reporting-Register-OS-Source que contém as informações de registro do SO precisam ser retornados ao especificar uma plataforma preferencial para garantir que o registro da plataforma correta possa ocorrer. Os registros do SO e da Web precisam ser fornecidos para que, se a plataforma preferencial não estiver disponível, as informações necessárias para o método alternativo estejam presentes.
```
Attribution-Reporting-Info: preferred-platform=os
```
- Para concluir o registro da origem, 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 precisa especificar um destino do 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 origem, o Chrome vai seguir os redirecionamentos e chamar as APIs de contexto da Web para cada salto de redirecionamento.
- O restante do registro de origem permanece o mesmo.
A adtech no app do anunciante registra um acionador com a API Attribution Reporting do Android:
- Para acionadores que ocorrem em apps, eles registram acionadores com a API Attribution Reporting do Android normalmente.

Campanhas com destinos em apps e na Web

Configurar destinos duplos
- Algumas campanhas podem ser configuradas para converter no app ou na página da Web do anunciante, dependendo de vários fatores, como se o usuário tem o app instalado.
- Nesses casos, é recomendável delegar o registro de origem ao SO, se disponível, para que a origem possa ser atribuída corretamente, independentemente de onde o gatilho ocorre. Ao registrar a origem no SO, um 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 da API Attribution Reporting do SO precisa ser um pacote de app, 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 vai explicar como o uso de destinos duplos pode afetar o ruído nos seus relatórios.
Use relatórios aproximados para reduzir o ruído nos relatórios de eventos para fontes de destino duplas:
- Se um destino da Web e um destino do SO (app) foram especificados no registro da origem, os relatórios no nível do evento vão especificar se o acionador ocorreu em um destino da Web ou do app por padrão. No entanto, para manter os limites de privacidade, ruídos adicionais serão adicionados 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 aproximados e reduzir o ruído. Se uma origem com o campo coarse_event_report_destinations especificado ganhar a atribuição, o relatório resultante vai incluir destinos da Web e do app sem distinção de onde o acionador real ocorreu, mas com menos ruído do que os relatórios em que o destino do app ou da Web é especificado.
- Os relatórios agregados não são alterados.

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 medir em apps e sites da Web para dispositivos móveis.

Registre uma origem de app e um acionador da guia personalizada:
- Siga as instruções para registrar uma fonte de app e um acionador da Web.
Registre uma fonte da guia personalizada e um acionador do 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 da Web de site para site no Chrome.

Para apps que usam a WebView

Alguns apps podem usar a WebView para mostrar conteúdo. Há vários casos de uso para a WebView, como renderizar anúncios, hospedar conteúdo da Web ou recursos personalizados de apps mais adequados a um formato da Web.

Para permitir que as WebViews usem a API Attribution Reporting, o app incorporado precisa ser configurado com as permissões corretas.
Somente a atribuição no nível do SO está disponível no WebView. O cabeçalho Attribution-Reporting-Support vai retornar apenas SO, e somente se a API Attribution Reporting do Android estiver disponível.

Observação: para fazer a atribuição no Chrome e na WebView, os registros de origem e acionador no Chrome precisam ser delegados ao SO, já que apenas a atribuição baseada no SO é compatível com a WebView.

Ao delegar para o SO, a WebView pode usar registerSource ou registerWebSource e registerTrigger ou registerWebTrigger. Quais métodos são usados pela WebView são definidos pelo app que renderiza a WebView e são determinados por WebView.

A diferença entre registerSource e registerWebSource é qual fonte é registrada como o editor. Com registerSource, o app é registrado como o editor. Um exemplo de quando usar registerSource seria um app de editor que mostra um anúncio renderizado usando a WebView. Com registerWebSource, o site hospedado na WebView é registrado como o editor. Um exemplo de quando usar registerWebSource seria um app que hospeda uma WebView, e o site que está sendo renderizado pela WebView está exibindo anúncios. registerTrigger e registerWebTrigger têm comportamentos semelhantes. O gráfico no item 3 detalha diferentes cenários em que um desenvolvedor de app ou SDK quer configurar a API para usar registerSource ou registerWebSource, e registerTrigger ou registerWebTrigger.

Por padrão, a WebView vai usar registerSource e registerWebTrigger ao chamar a API Attribution Reporting do Android. Isso associa fontes ao app e aciona a origem de nível superior do URL na WebView quando o acionador ocorre.

Se um app exigir um comportamento diferente, ele precisará usar um novo método setAttributionRegistrationBehavior na classe androidx.webkit.WebViewSettingsCompat. Esse método especifica se a WebView precisa chamar registerWebSource() ou registerWebTrigger(), em vez de registerSource() ou registerTrigger().
Esse comportamento precisa ser definido para cada WebView iniciada.
Se o SDK de adtech estiver iniciando a WebView, ele precisará definir esse comportamento padrão.
Para apps que gostariam de usar registerWebSource() para associar registros de origem ao site na WebView em vez do app, é necessário participar da lista de permissões do WebApp. Preencha este formulário para participar da lista de permissões. O intuito da lista de permissões é reduzir as considerações de privacidade sobre como estabelecer a confiança no contexto da Web.

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 origem e acionador da WebView
As adtechs precisam responder aos registros de origem 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 da API Android Attribution Reporting para o URI da adtech.
- Para concluir o registro da origem, o endpoint da adtech precisa responder à solicitação da API Attribution Reporting do Android com o cabeçalho de resposta.
```
 Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}
```
O restante do registro de origem 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 iniciar uma chamada de API secundária do Rb para o URI da adtech.
Para concluir o registro do acionador, o endpoint da adtech precisa responder à solicitação da API Attribution Reporting do Android com o cabeçalho de resposta.

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 de acionadores permanece o mesmo.

Depurar

Ao configurar uma implementação de app para Web, é recomendável configurar relatórios de depuração para verificar se as origens e os acionadores estão sendo registrados corretamente e, se não estiverem, receber informações sobre o motivo.

Para etapas gerais de depuração de relatórios de atribuição, consulte o livro de receitas de depuração.