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

Este guia ensina 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 se familiarizar com as soluções de depuração disponíveis para verificar se a configuração está funcionando conforme o esperado.

Registrar fontes e acionadores com o SO Android

A atribuição entre apps e na Web só 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 "os", "web" ou ambos, dependendo do que estiver disponível no dispositivo. Se ambos estiverem disponíveis, as adtechs poderão registrar fontes 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 ambos ao SO. Para campanhas somente na Web em que a origem ou o acionador podem ocorrer em uma WebView, as adtechs precisam delegar os registros de origem e acionador ao SO. Consulte a seção sobre WebViews para mais informações.

  • As adtechs precisam evitar registrar fontes e acionadores com as APIs do Chrome e do Android simultaneamente para não criar relatórios de atribuição duplicados.

  • A atribuição acontece separadamente para navegadores e o SO. Se uma origem for registrada no navegador, mas o acionador for registrado no SO, esses dois não poderão ser correspondidos, e vice-versa.

  • Para fontes que podem resultar em um acionador de app ou da Web, é altamente recomendável que a adtech delegue os registros de fonte e acionador da Web à API Attribution Reporting do Android.

  • Para acionadores que podem ter sido gerados por fontes baseadas em apps, a adtech pode delegar o registro de acionadores da Web à API Attribution Reporting do Android.

  • Para campanhas em que a origem e o acionador ocorrem em um app, ambos precisam ser registrados com a 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 para dispositivos móveis no mesmo dispositivo.

Exemplo

Um usuário está lendo artigos no app de notícias favorito dele. 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 para a página da Web do anunciante no Chrome, onde pode fazer uma conversão. 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 registrar diretamente com a API Attribution Reporting do Chrome. Em seguida, a API Attribution Reporting no nível do SO consegue corresponder à origem do app e ao acionador da Web e enviar os relatórios relevantes.

Fluxo de atribuição de app para Web
Fluxo de atribuição de app para Web

Registro da origem do app:

  1. O SDK de adtechs no app Android Daily News registra o clique usando registerSource()

  2. A API Attribution Reporting no Android envia uma solicitação ao URL do servidor de adtech fornecido para registerSource()

  3. O servidor de adtech responde com o cabeçalho Attribution-Reporting-Register-Source para concluir o registro da origem.

Registro de acionadores da Web:

  1. A adtech registra um acionador e verifica a disponibilidade do SO na API Attribution Reporting.

  2. A ARA da Web retorna informações sobre qual plataforma tem suporte.

  3. O cabeçalho OS-Trigger informa à API Web ARA para chamar a função registerWebTrigger() da API OS ARA.

  4. A chamada para registerWebTrigger() acontece nos bastidores, e o desenvolvedor não precisa chamar registerWebTrigger() diretamente com o SO.

  5. A ARA do SO assume o controle e envia uma solicitação ao URL do servidor de adtech fornecido pelo cabeçalho Attribution-Reporting-Register-OS-Trigger

  6. A adtech vai concluir o registro do acionador com a API do SO.

  7. A 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:

  1. 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 gerar uma conversão 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 de app.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
    • Alguns anunciantes podem estar usando vários provedores de medição (por exemplo, uma ferramenta de medição de terceiros ou uma ferramenta de análise) com cadeias de redirecionamento 302. Em alguns casos, a API Attribution Reporting segue o caminho de redirecionamento especificado no cabeçalho "Attribution-Reporting-Redirect" em segundo plano e, ao mesmo tempo, o caminho de redirecionamento 302 é executado em primeiro plano para solicitações de navegação atuais. Essas solicitações vão para o mesmo URL e podem resultar em uma contagem dupla de registros pelo provedor de medição de terceiros. Para evitar a contagem dupla de registros, as adtechs podem modificar o comportamento de redirecionamento para enviar o registro da API Attribution Reporting a um URL alternativo, mas 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 precisa ser redirect-302-to-well-known
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • O restante do processo de registro de origem é o mesmo de um registro de origem padrão de app para app.

  2. 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 no Chrome.

      1. Um pixel ou uma solicitação fetch() pode ser usado 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

    • Em seguida, a adtech precisa informar ao Chrome para delegar ao SO usando o cabeçalho Attribution-Reporting-Register-OS-Trigger, que:

      1. Diz 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 nos bastidores, e a adtech não precisa chamar registerWebTrigger() diretamente.

      3. A API do SO inicia uma chamada de API secundária para o URI de 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 não está disponí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.

    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"]}
    ],
    ...
}

Registrar uma fonte da Web e um acionador de app

Em algumas campanhas, uma fonte 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 em um smartphone Android. Eles veem um anúncio de um suéter de uma das lojas favoritas. Eles clicam no anúncio e são direcionados para o app que já baixaram. 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 consegue corresponder à fonte da Web e ao acionador do app e enviar os relatórios relevantes.

Fluxo de atribuição de Web to App
Fluxo de atribuição do Web to App

Registro de fontes da Web:

  1. A adtech registra uma fonte e verifica a disponibilidade do SO na API Attribution Reporting.

  2. A ARA da Web retorna informações sobre qual plataforma tem suporte.

  3. O cabeçalho OS-Source informa à API Web ARA para chamar a função registerWebSource() da API OS ARA.

  4. A chamada para registerWebSource() acontece nos bastidores, e o desenvolvedor não precisa chamar registerWebSource() diretamente com o SO.

  5. A ARA do SO assume o controle e envia uma solicitação ao URL do servidor de tecnologia de publicidade fornecido pelo cabeçalho Attribution-Reporting-Register-OS-Source.

  6. A adtech vai concluir o registro da origem com a API do SO

Registro de acionadores de apps:

  1. O SDK de adtech no app Android da loja de roupas registra o acionador com a ARA do SO.

  2. A API Attribution Reporting no Android envia uma solicitação ao URL do servidor de adtech fornecido para registerTrigger()

  3. O servidor de adtech responde com o cabeçalho Attribution-Reporting-Register-Trigger para concluir o registro do acionador.

  4. A 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:

  1. A adtech no site do publisher registra a origem instruindo o Chrome a delegar o registro à API Attribution Reporting do Android:

    • Para um caso de uso da Web para app, ao registrar uma origem, o parâmetro de origem de atribuição precisa ser especificado diretamente usando a tag attributionsrc ou o registro em 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">

  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

  3. 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. Diz 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 nos bastidores. A adtech não precisa chamar registerWebSource() diretamente.
    4. A API do SO inicia uma chamada de API secundária para o URI de adtech transmitido pelo 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 preferida para processar o registro de 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 não estiver disponível.
    Attribution-Reporting-Info: preferred-platform=os
    • Para concluir o registro de 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 de app no campo "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.

  4. 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 potencial para apps e na Web

  1. Configurar destinos duplos

    • Algumas campanhas podem ser configuradas para gerar conversões 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 quando disponível para que a origem possa ser atribuída corretamente, independente de onde o gatilho ocorre. Ao registrar a origem com o SO, um destino de app e da Web pode ser especificado 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 saber 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 explica como o uso de destinos duplos pode afetar o ruído nos seus relatórios.

  2. Use relatórios aproximados para reduzir o ruído nos relatórios de eventos de fontes de destino duplo:

    • Se um SO (app) e um destino da Web forem especificados no registro da origem, os relatórios no nível do evento vão especificar por padrão se o acionador ocorreu em um destino da Web ou de app. No entanto, para manter os limites de privacidade, um ruído adicional 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 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 relatórios em que o destino da Web ou do app é 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 maneira semelhante a uma página da Web comum ao medir em apps e sites para dispositivos móveis.

  1. Registre uma origem de app e um acionador de guia personalizada:

  2. Registre uma fonte de guia personalizada e um acionador de app:

  3. Registrar uma fonte e um acionador da CCT

Para apps que usam WebView

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

  1. Para permitir que as WebViews usem a API Attribution Reporting, o app de incorporação precisa ser configurado com as permissões corretas.

  2. Apenas a atribuição no nível do SO está disponível na WebView. O cabeçalho "Attribution-Reporting-Support" vai retornar apenas o SO e somente se a API Attribution Reporting do Android estiver disponível.

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

    • A diferença entre registerSource e registerWebSource é qual fonte é registrada como publisher. 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 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 renderizado pela WebView está mostrando anúncios. registerTrigger e registerWebTrigger têm comportamentos semelhantes. O gráfico no item 3 detalha diferentes cenários em que um desenvolvedor de apps 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 tecnologia de publicidade estiver iniciando a WebView, ele precisará definir esse comportamento padrão.

      • Os apps que quiserem usar registerWebSource() para associar registros de origem ao site na WebView em vez do app precisam participar da lista de permissões de WebApp. Preencha este formulário (em inglês) para participar da lista de permissões. O objetivo 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.
    1. Registros de fonte e acionador da WebView

    2. 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 Attribution Reporting do Android para o URI da adtech.

      • Para concluir o registro de 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",
  ...
}

    3. O restante do registro de origem permanece o mesmo.

    4. 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.

    5. 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"]}
    ],
    ...
}

Depurar

Ao configurar uma implementação de app para Web, recomendamos 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 da API Attribution Reporting, consulte o manual de depuração.