API Attribution Reporting: medição entre apps e na Web

Atualizações recentes

• Adicionamos uma seção sobre relatórios de depuração transicionais.
• Adicionamos instruções sobre como participar de uma lista de permissões para registrar fontes da Web.

Conforme descrito na proposta de design da API Attribution Reporting, a API permite a atribuição dos caminhos de acionadores abaixo em um único dispositivo Android:

• De app para app: o usuário encontra um anúncio em um app e faz uma conversão nele ou em outro app instalado.
• De app para a Web: o usuário vê um anúncio em um app e faz uma conversão em um navegador para dispositivos móveis ou no navegador de um app.
• Da Web para um app: o usuário vê um anúncio em um navegador de um app ou para dispositivos móveis e faz uma conversão em um app.
• Da Web para a Web: o usuário vê um anúncio em um navegador para dispositivos móveis ou app navegador e realiza uma conversão nesse navegador ou em outro no mesmo dispositivo.

Aqui, "Web" é definida como o conteúdo da Web mostrado em um app. Esse conteúdo pode ser mostrado no contexto de um app navegador para dispositivos móveis ou como sites incorporados mostrados em apps que não são de navegação.

Os caminhos de acionadores acima exigem estes requisitos:

• Para adtechs: atualizações em chamadas de API e relatórios para ativar os caminhos do app para a Web.
• Para apps e navegadores: capacidade de transmitir o registro de fontes de atribuição e acionadores da Web para o Android.

Neste documento, explicamos como a API Attribution Reporting é estendida para oferecer suporte a caminhos de acionadores de app para a Web, da Web para app e da Web para a Web. Também descreve as mudanças que as adtechs e os apps precisam fazer para atender aos requisitos de suporte desses caminhos de acionadores.

Como acessar as APIs Attribution Reporting

As plataformas de adtech precisam se registrar para acessar as APIs Attribution Reporting. Confira Registrar uma conta do Sandbox de privacidade para mais informações.

Depois que o processo for finalizado, a API vai descartar o registro se uma chamada não registrada for recebida.

As plataformas de adtech precisam garantir que estejam registrando todos os URLs de servidor que elas podem usar no app e na Web para registrar acionadores e fontes de atribuição. Há suporte a vários URLs de registro de servidor, mas para apenas uma origem de relatório. Essa origem é derivada do domínio de um dos URLs de registro de servidor.

Mudanças para adtechs

Esta seção discute as mudanças para adtechs que usam a API Attribution Reporting.

Mudanças no registro e na atribuição

Ao registrar uma fonte de atribuição, as adtechs especificam um campo de destino, que é o nome do pacote do app em que ocorre o evento acionador. Para ativar a medição de app para a Web, planejamos oferecer suporte a um campo de destino do app (nome do pacote do app) e a um campo de destino da Web (eTLD+1).

Ao registrar fontes ou acionadores de atribuição da Web, a API não oferece suporte para redirecionamentos, porque cada app que hospeda conteúdo da Web pode ter o próprio modelo de permissões. Cada app é responsável por seguir os redirecionamentos, se houver suporte, e chamar as APIs de contexto da Web para cada salto de redirecionamento.

Além disso, essa integração permite que as adtechs usem a lógica de atribuição específica do app em fontes de atribuição da Web. Por exemplo, agora você pode especificar janelas de atribuição pós-instalação em uma fonte de atribuição da Web.

Receber relatórios de apps e da Web

A API Attribution Reporting do Android pode enviar relatórios para conversões na Web e de app. Se as adtechs não quiserem alinhar os dados do acionador e as chaves-valor de agregação nas superfícies do app e da Web, elas poderão distinguir entre uma conversão na Web e de app:

• Para relatórios de eventos, vamos aceitar um campo de destino que especifica se o acionador foi ativado na Web (o destino é um eTLD+1) ou no app (o destino é o nome de um pacote de app).
• Para relatórios agregáveis, o destino será enviado em texto não criptografado.

Implicações de medição da Web para a Web

Os apps escolhem quando transmitir o registro para a API Attribution Reporting. Há vários pontos a se considerar aqui:

• A API Attribution Reporting está disponível no dispositivo? Vamos mostrar um novo indicador para os apps, que informa se a API Attribution Reporting está ou não disponível no dispositivo. Consulte a seção de mudanças para apps e veja mais detalhes sobre como os aplicativos podem transmitir o registro para a API Attribution Reporting.
• Que parte dos acionadores e das fontes de atribuição precisa ser transmitida para a API? Essa decisão será tomada pelo app ou pela adtech se o app permitir. Caso o app tenha a própria solução de métricas, o uso dela pode ser recomendado. Em última análise, transmitir todos os registros de acionador e fonte para a API Attribution Reporting do Android, quando disponível, permite a atribuição mais precisa em apps e na Web.

O exemplo a seguir mostra como os apps de navegador funcionam com a API Attribution Reporting para fornecer uma medição precisa quando o usuário clica em um anúncio em um app navegador e um que não é de navegação:

• No primeiro dia, o usuário clica em um anúncio no app navegador.
  • Esse app pode usar a própria solução de métricas ou transmitir o registro do clique no anúncio da Web para a API Attribution Reporting.
• No segundo dia, o usuário clica em um anúncio em um app que não é de navegação.
  • O clique é registrado como uma fonte de atribuição com a API. O app navegador não tem visibilidade desse clique, porque o evento ocorreu em outro aplicativo.
• No terceiro dia, o usuário faz a conversão no app navegador.
  • Se o app navegador registrar o clique e a conversão usando a própria solução de métricas e transmitir as informações para a API Attribution Reporting, é improvável que uma adtech consiga eliminar a duplicação dos relatórios de conversão nas soluções de métricas. Além disso, uma adtech pode consumir os limites de taxa do app navegador e da API Attribution Reporting. Por isso, recomendamos que os apps transmitam todos os eventos e conversões de anúncio que serão registrados na API, quando ela estiver disponível.

Registrar a fonte de atribuição e o acionador da WebView

Caso o app esteja usando a WebView para mostrar conteúdo da Web em vez de um anúncio nativo do Android, o app poderá se registrar para participar da lista de permissões (link em inglês) de registerWebSource() e fornecer a origem do site de nível superior a ser associada à fonte de atribuição, e não ao nome do pacote do app.

Assim como os navegadores, a WebView oferece suporte ao método registerWebTrigger() para registros de acionadores, que associam o acionador à origem de nível superior. A WebView não permite registrar um acionador de app. Entre em contato (link em inglês) se você tiver um caso de uso para isso. Para conferir a lista completa de combinações com suporte da WebView, consulte Registro do acionador e da fonte de atribuição da WebView.

Ao contrário dos navegadores, a WebView só vai permitir o registro no SO no cabeçalho Attribution-Reporting-Eligible se a API Attribution Reporting do Android estiver disponível. Se a API Attribution Reporting do Android não estiver disponível, a WebView não definirá um cabeçalho Attribution-Reporting-Eligible e nenhum registro será feito.

Para registrar um acionador / uma fonte de atribuição usando o SO:

• As adtechs precisam responder aos registros de origem usando o cabeçalho Attribution-Reporting-Register-OS-Source, que inicia uma chamada de API secundária da WebView para registerSource() ou registerWebSource().
• A adtech também pode responder a registros de acionador usando o cabeçalho Attribution-Reporting-Register-OS-Trigger, que inicia uma chamada de API secundária da WebView para registerWebTrigger() ou registerTrigger().

Se a resposta não incluir os cabeçalhos anteriores ou também incluir os cabeçalhos Attribution-Reporting-Register-Source / Attribution-Reporting-Register-Trigger, mesmo que não haja suporte para a Web, todo o registro vai falhar.

Para saber se a WebView vai usar registerSource() / registerWebSource() e registerTrigger() / registerWebTrigger() e como mudar esse comportamento, consulte Registro do acionador e da fonte de atribuição da WebView.

Relatórios de depuração transicionais

A API Attribution Reporting oferece suporte a um recurso opcional chamado relatórios de depuração transicionais, que mostra às adtechs mais informações sobre os relatórios de atribuição quando um ID de publicidade está disponível. Há dois tipos de relatórios de depuração: atribuição concluída e detalhado. Esses relatórios têm suporte na atribuição entre apps e na Web e contêm as mesmas informações. A única diferença entre eles são as permissões que definem quando os relatórios de depuração são enviados.

Na atribuição da Web para a Web que ocorre em um único app (por exemplo, no mesmo app de navegador), relatórios detalhados e de atribuição concluída ficam disponíveis somente quando cookies de terceiros também estiverem, e não com base na disponibilidade do ID de publicidade.

Na atribuição de app para a Web, da Web para um app e da Web para a Web, relatórios de atribuição concluída e detalhados vão estar disponíveis se o ID de publicidade estiver disponível no lado do app e a adtech puder transmitir o mesmo ID de publicidade (correto) no lado da Web.

Em um exemplo posterior de app para a Web, a origem é um app do editor, mas o acionador ocorre no site de um anunciante em um app de navegador.

Para ativar um relatório de depuração de atribuição concluída na atribuição do app para a Web, as seguintes condições precisam ser atendidas:

• O usuário não pode ter desativado a personalização usando o ID de publicidade.
• O app do editor precisa ter permissões de ID de publicidade declaradas.
• A adtech precisa transmitir o valor do ID de publicidade no registro do acionador (de um contexto da Web).

Para ativar relatórios de depuração detalhados na atribuição do app para a Web:

• Os relatórios detalhados de origem dependem apenas das permissões do editor. Para que relatórios detalhados da fonte sejam enviados, o usuário não pode ter desativado a personalização do ID de publicidade, e o app do editor precisa ter declarado permissões desse ID.
• Os relatórios detalhados do acionador dependem das permissões do acionador (neste exemplo, apenas permissões da Web). Cookies de terceiros precisam estar disponíveis no navegador para que os relatórios detalhados sejam enviados.
• Relatórios detalhados do acionador poderão incluir uma source_debug_key. A source_debug_key será incluída se o ID de publicidade estiver disponível para o app do editor.

Em todos os casos, a adtech ainda precisa ativar o recebimento de relatórios de depuração detalhados usando o campo de dicionário debug_reporting nos cabeçalhos de registro de origem e acionador.

Mudanças para apps

Vamos oferecer suporte à atribuição entre as superfícies do app e da Web permitindo que os apps transmitam o registro de fontes de atribuição e acionadores da Web à API Attribution Reporting do Android usando um novo conjunto de chamadas da API de contexto da Web.

Depois de concluir as etapas de registro nas próximas seções, os acionadores e as fontes de atribuição de apps e da Web são armazenados no dispositivo, e a API Attribution Reporting pode executar a atribuição de último toque priorizada pela fonte nas superfícies do app e da Web.

Consulte a proposta do Sandbox de privacidade para a Web (link em inglês) e confira um exemplo de como os navegadores podem se integrar à API Attribution Reporting do Android para ativar a medição entre apps e na Web. Na proposta, o navegador vai adicionar estes cabeçalhos de solicitação:

• Attribution-Reporting-Eligible transmite se o suporte no nível do SO para atribuição está disponível. Nesse caso, o cabeçalho indica se a API Attribution Reporting do Android está disponível.
• Se estiver, a adtech poderá responder usando Attribution-Reporting-Register-OS-Source, que inicia uma chamada de API secundária do app de navegador para registerWebSource().
• A adtech também pode responder a registros de acionador usando o cabeçalho Attribution-Reporting-Register-OS-Trigger, que inicia uma chamada de API secundária do app do navegador para registerWebTrigger().

Registro de fonte de atribuição

Ao registrar uma fonte de atribuição, os apps podem chamar o método registerWebSource(), que precisa destes parâmetros:

• URIs de fonte de atribuição: a plataforma emite uma solicitação para cada URI nesta lista para buscar os metadados associados à fonte de atribuição.
  
  Cada URI precisa acompanhar uma flag booleana de depuração para indicar se as chaves fornecidas pelas adtechs precisam ser incluídas ou não no relatório.
• Evento de entrada: é um objeto InputEvent em um evento de clique. No caso de uma visualização, é null.
• Origem da fonte: origem em que a fonte ocorreu (site do editor).
• Destino do SO: nome de um pacote de app em que ocorre o evento acionador.
• Destino da Web: um eTLD+1 em que o evento acionador acontece.
• Destino verificado: URI/intent de destino da Web ou do SO que foi usado para navegação após o clique do usuário.

Quando a API faz uma solicitação para o URI da fonte de atribuição, a adtech precisa responder com os metadados da fonte de atribuição em um cabeçalho HTTP, Attribution-Reporting-Register-Source. Esse cabeçalho usa os mesmos campos do registro de fonte de atribuição de app a app, com algumas mudanças:

• A API valida os destinos especificados pela adtech com aqueles definidos pelo app. Se os destinos forem diferentes, a API vai descartar o registro da fonte de atribuição.
  
  O esperado é que os apps validem destinos da Web antes de chamar a API de contexto da Web. No caso dos cliques, os apps precisam verificar se o destino especificado corresponde àquele para o qual o usuário está navegando.
• A API ignora todos os URIs de redirecionamento fornecidos em Attribution-Reporting-Redirects. Os apps precisam seguir redirecionamentos por conta própria e chamar o registerWebSource() para cada um deles, de modo que possam aplicar as próprias políticas de permissões conforme necessário.

Os apps precisam estar em uma lista de permissões para chamar registerWebSource(). Preencha este formulário (em inglês) 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.

Registro do acionador (conversão)

No registro do acionador, os apps podem chamar o registerWebTrigger(), que precisa dos seguintes parâmetros:

• URIs de acionador: a plataforma emite uma solicitação para cada URI nesta lista de modo a buscar os metadados associados ao acionador.
• Origem do destino: a origem em que o acionador foi ativado (site do anunciante).

Registro do acionador e da fonte de atribuição da WebView

Por padrão, a WebView vai usar registerSource() e registerWebTrigger(). Isso associa fontes ao app e aciona a origem de nível superior da WebView quando o acionador ocorre.

Se um app exigir um comportamento diferente (como aqueles que hospedam conteúdo da Web em uma WebView), ele precisará usar o método setAttributionRegistrationBehavior na classe androidx.webkit.WebViewSettingsCompat. Esse método especifica se a WebView precisa chamar registerWebSource() ou registerSource() e registerWebTrigger() ou registerTrigger().

As opções disponíveis para setAttributionRegistrationBehavior são as seguintes:

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. Observação: os apps que usam essa opção precisam se registrar para participar da lista de permissões e usar registerWebSource().	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.
DISABLED	Desativa o registro de fonte e acionador da WebView. A chamada de rede inicial para os URIs do acionador ou da fonte de atribuição ainda pode acontecer, mas qualquer resposta será descartada e nada será armazenado no dispositivo.

Considerações sobre privacidade e segurança

Esta seção aborda as considerações de privacidade e segurança para apps que usam a API Attribution Reporting.

Impacto nos mecanismos de preservação da privacidade aplicados aos relatórios

Conforme descrito na proposta de design principal, a API aplica limites de taxa de preservação da privacidade aos relatórios. Alguns limites são particionados entre apps de fonte e destino. Quando uma fonte ou um acionador de atribuição da Web é registrado, o limite de taxa é particionado pelo site de fonte ou destino em vez do app.

Caso o app mantenha limites de taxa separados, um adversário poderia consumir os limites de taxa específicos do app, além dos limites de taxa da API. Para atenuar isso, os apps precisam garantir que uma determinada fonte de atribuição não esteja registrada na solução de métricas do app e na API Attribution Reporting do Android.

Estabelecer confiança no contexto da Web

Nas chamadas de API de contexto da Web, a API confia no app para detectar e especificar as origens de fonte e destino. Isso pode levar a possíveis considerações de privacidade e segurança:

• Um adversário pode afirmar que hospeda sites próprios para tentar burlar limites de taxa da quantidade de informações que qualquer fonte pode transferir.
• Vários adversários podem colaborar para registrar fontes de atribuição diferentes, reivindicando o mesmo site de fonte. Isso pode fazer com que o site de fonte alcance os limites de taxa da plataforma de adtech e pode impedir que o site real registre fontes de atribuição legítimas.

Para atenuar isso, vamos limitar a chamada de registerWebSource() a navegadores ou apps que atestem que o site de fonte usado no registro representa o site real que está sendo mostrado ao usuário. Preencha o formulário de registro de relatórios de atribuição da Web para o app para participar da lista de permissões e chamar registerWebSource().

Qualquer app pode chamar o registerWebTrigger(), porque as considerações de privacidade e segurança no lado do acionador não são aplicáveis sem a colusão do lado da fonte.

Controles de usuário

Os apps podem manter o suporte para as políticas de controles ou permissões do usuário, desde que a definição possa ser feita no momento do registro. Por exemplo, se os apps autorizarem permissões no nível do site ou do usuário, eles vão precisar avaliar essas permissões e determinar se as APIs de contexto da Web devem ser chamadas.

Além disso, vamos oferecer suporte para uma nova chamada de API por apps para excluir qualquer fonte de atribuição, acionadores e relatórios pendentes armazenados para esse app no dispositivo. Por exemplo, se o app permite que o usuário limpe o histórico de navegação, ele pode chamar a API para excluir as fontes de atribuição, os acionadores e os relatórios pendentes armazenados para esse app no dispositivo.

Considerações futuras e perguntas em aberto

A interoperabilidade do app para a Web da API Attribution Reporting está fase de desenvolvimento. Gostaríamos de receber feedback da comunidade quanto a algumas ideias:

1. Em um dispositivo com suporte para o Sandbox de privacidade do Android, como você vai usar as solução de métricas do navegador com a API Attribution Reporting do Android? Você prefere transmitir tudo para o Android?
2. Há alguma preocupação sobre o possível recebimento de dois pings para cada fonte e acionador de atribuição, um do navegador ou app e outro da API Attribution Reporting?
3. Como podemos facilitar a depuração em diferentes APIs?
4. A proposta não inclui a validação de que destinos da Web e de apps são afiliados. No futuro, poderemos validar esses destinos verificando as associações com os Digital Asset Links. Isso bloquearia algum dos seus casos de uso? Faz sentido usar Digital Asset Links para essa validação?
5. Ao registrar uma fonte de atribuição, você precisa especificar um destino. No caso da Web para o app, é recomendável especificar um link de app. Quais formatos você usa para especificar o link desse app?
6. Ao registrar uma fonte de atribuição de app para a Web, esse evento de origem precisa ser registrado no app com a API Attribution Reporting do Android. Por exemplo, se o usuário clicar em um anúncio e ele for aberto em uma guia personalizada ou em um navegador, esse clique (evento de origem) precisará ser registrado no app, e não no contexto do navegador. Entre em contato se tiver dúvidas sobre isso ou se houver outros casos de uso que não se enquadram nas categorias abordadas neste tópico, descrevendo os fluxos que têm suporte (link em inglês).

Recomendados para você

• Observação: o texto do link aparece quando o JavaScript está desativado.
• Como gerar relatórios de atribuição
• Guia da API Attribution Reporting para desenvolvedores
• Notas da versão