Esta página foi traduzida pela API Cloud Translation.

Visão geral da API Attribution Reporting para dispositivos móveis

Atualizações recentes

Atualizamos a lista das futuras mudanças e problemas conhecidos.
Introduzimos a configuração flexível de eventos do Lite como uma ponte para a configuração flexível de eventos completa.
A partir de setembro de 2023, registerWebSource, registerWebTrigger, registerAppSource e registerAppTrigger precisam usar strings para campos que esperam um valor numérico (como priority, source_event_id, debug_key, trigger_data, deduplication_key etc.).
A partir do quarto trimestre de 2023, o Google Cloud terá suporte à API Attribution Reporting do Android para gerar relatórios de resumo usando o serviço de agregação no Google Cloud. Isso será refletido aqui. Consulte o guia de implantação para mais informações sobre como configurar o serviço de agregação com o Google Cloud.
Novos limites de taxa que preservam a privacidade para o número de destinos exclusivos.
A funcionalidade atualizada para filtros do acionador da janela de lookback será lançada no primeiro trimestre de 2024. Consulte a observação para mais informações.

Visão geral

Atualmente, é comum que as soluções de atribuição e de métricas de dispositivos móveis usem identificadores entre partes diferentes, por exemplo, o ID de publicidade. A API Attribution Reporting foi projetada para melhorar a privacidade do usuário, eliminando a necessidade de compartilhar identificadores de usuário entre diferentes partes. Ela também permite oferecer suporte aos principais casos de uso para avaliação de métricas de conversões e para atribuição em apps e na Web.

Essa API inclui os mecanismos estruturais abaixo que oferecem um framework para melhorar a privacidade e que vão ser apresentados em mais detalhes nas próximas seções desta página:

Limita o número de bits disponíveis para relatórios de eventos
Permite dados de conversão com maior fidelidade somente em relatórios agregáveis
Apresenta a limitação de taxa para acionadores disponíveis (conversões) e o número de adtechs que podem ser associadas a uma única fonte de atribuição
Incorpora várias técnicas de adição de ruído

Os mecanismos anteriores limitam a capacidade de estabelecer uma relação sobre a identidade do usuário entre dois apps ou domínios diferentes.

A API Attribution Reporting oferece suporte aos casos de uso abaixo:

Relatórios de conversão: ajudam os anunciantes a medir a performance das campanhas ao apresentar as métricas e os valores de conversões (acionadores) em diferentes dimensões, como por campanha, por grupo de anúncios ou por criativo de anúncio.
Otimização: gera relatórios de evento que ajudam a otimizar os gastos com publicidade, fornecendo dados de atribuição por impressão que podem ser usados para treinar modelos de ML.
Detecção de atividade inválida: gera relatórios que podem ser usados para detecção e análise de tráfego inválido e de fraudes de anúncios.

De modo geral, a API Attribution Reporting funciona da maneira descrita abaixo, e vamos mostrar mais detalhes nas próximas seções deste documento.

A adtech é registrada para usar a API Attribution Reporting.
A adtech registra fontes de atribuição (cliques ou visualizações de anúncios) usando a API Attribution Reporting.
A adtech registra acionadores (conversões de usuários no app ou no site do anunciante) usando a API Attribution Reporting.
A API Attribution Reporting combina acionadores às fontes de atribuição, ou seja, uma atribuição de conversão. Em seguida, um ou mais acionadores são incluídos em relatórios de eventos e relatórios agregáveis, que são enviados do dispositivo para as adtechs.

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.

Registrar uma fonte de atribuição (clique ou visualização)

Na API Attribution Reporting, as visualizações e os cliques em anúncios têm o nome fontes de atribuição. Para registrar um clique ou uma visualização de anúncio, chame registerSource(). Essa API espera receber os parâmetros abaixo:

URI da fonte de atribuição: a plataforma emite uma solicitação a esse URI para buscar metadados associados à fonte de atribuição.
Evento de entrada: é um objeto InputEvent em um evento de clique. No caso de uma visualização, é null.

Quando a API faz uma solicitação para o URI da fonte de atribuição, a adtech precisa responder com os metadados dessa fonte em um novo cabeçalho HTTP Attribution-Reporting-Register-Source, incluindo estes campos:

ID do evento da fonte: esse valor representa os dados de evento associados a essa fonte de atribuição (clique ou visualização do anúncio). Ele precisa ser um número inteiro não assinado de 64 bits formatado como uma string.
Destino: uma origem com o nome de eTLD+1 ou do pacote do app em que acontece o evento acionador.
Validade (opcional): período de validade, em segundos, após o qual a fonte precisa ser excluída do dispositivo. O padrão é 30 dias, com um valor mínimo de um dia e máximo de 30. Esse número é arredondado para o dia mais próximo. Pode ser formatado como um número inteiro não assinado ou string de 64 bits.
Janela de relatórios de eventos (opcional): duração em segundos após o registro da fonte em que os relatórios de eventos podem ser criados. Se a janela de relatórios de eventos tiver passado, mas a expiração ainda estiver pendente, a correspondência de um acionador com uma fonte ainda poderá ser feita, mas um relatório de eventos não será enviado para esse acionador. Não pode ser maior que a validade. Pode ser formatado como um número inteiro não assinado ou string de 64 bits.
Janela de relatórios agregáveis (opcional): duração em segundos após o registro da fonte em que os relatórios agregáveis podem ser criados para essa fonte. Não pode ser maior que a validade. Pode ser formatado como um número inteiro ou string não assinado de 64 bits.
Prioridade da fonte (opcional): usada para selecionar a qual fonte de atribuição um determinado acionador precisa ser associado, caso várias fontes de atribuição possam ser associadas ao acionador. Precisa ser um número inteiro assinado de 64 bits formatado como uma string.

Quando um acionador é recebido, a API encontra a fonte de atribuição correspondente com o valor de prioridade de fonte mais alto e gera um relatório. Cada adtech pode definir a própria estratégia de priorização. Para mais detalhes sobre como a prioridade afeta a atribuição, consulte a seção sobre exemplos de priorização.

Valores mais altos indicam prioridades maiores.
Janelas de atribuição de instalação e pós-instalação (opcional): usadas para determinar a atribuição dos eventos pós-instalação, descritos mais adiante nesta página.
Filtragem de dados (opcional): usada para filtrar seletivamente e ignorar alguns acionadores. Para mais detalhes, consulte a seção Filtros de acionador nesta página.
Chaves de agregação (opcional): especificam a segmentação a ser usada para relatórios agregáveis.

Opcionalmente, a resposta de metadados da fonte de atribuição pode incluir outros dados no cabeçalho Redirecionamentos dos relatórios de atribuição. Os dados contêm URLs de redirecionamento para que várias adtechs possam registrar uma solicitação.

O guia para desenvolvedores inclui exemplos que mostram como aceitar o registro de fonte.

As etapas abaixo mostram um exemplo de fluxo de trabalho.

O SDK da adtech chama a API para iniciar o registro da fonte de atribuição, especificando um URI para a API chamar:

registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);

A API faz uma solicitação para https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA usando um dos cabeçalhos abaixo:

<!-- For click events -->
Attribution-Reporting-Source-Info: navigation

<!-- For view events -->
Attribution-Reporting-Source-Info: event

O servidor HTTPS dessa adtech responde com cabeçalhos contendo o seguinte:

Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5"
}
Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

A API faz uma solicitação para cada URL especificado em Attribution-Reporting-Redirect. Neste exemplo, são especificados dois URLs de parceiros de adtech. Então, a API faz uma solicitação para https://adtechpartner1.example?their_ad_click_id=567 e outra para https://adtechpartner2.example?their_ad_click_id=890.
O servidor HTTPS dessa adtech responde com cabeçalhos contendo o seguinte:
```
Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}
```
Observação: as respostas das adtechs podem especificar metadados diferentes no cabeçalho Attribution-Reporting-Register-Source.

Três fontes de atribuição de navegação (cliques) são registradas com base nas solicitações apresentadas nas etapas anteriores.

Registrar uma fonte de atribuição da WebView

A WebView permite o caso de uso em que um app renderiza um anúncio em uma WebView. Isso é processado pela WebView chamando registerSource() diretamente como uma solicitação em segundo plano. Essa chamada associa a fonte de atribuição ao app em vez da origem de nível superior. Também há suporte para o registro de origens de conteúdo da Web incorporado no contexto do navegador. Tanto os autores das chamadas quanto os apps precisam ajustar as configurações. Consulte Registrar a fonte de atribuição e o acionador da WebView para instruções sobre autores de chamadas de API e o Registro do acionador e da fonte de atribuição da WebView para instruções relacionadas a apps.

Como as adtechs usam código comum na Web e na WebView, esta última segue redirecionamentos HTTP 302 e transmite os registros válidos para a plataforma. Não pretendemos oferecer suporte ao cabeçalho Attribution-Reporting-Redirect para esse cenário, mas entre em contato se você tiver um caso de uso afetado.

Registrar um acionador (conversão)

As adtechs podem registrar acionadores, que são conversões como instalações ou eventos pós-instalação, usando o método registerTrigger().

O método registerTrigger() espera receber o parâmetro URI do acionador. A API emite uma solicitação a esse URI para buscar metadados associados ao acionador.

A API segue os redirecionamentos. A resposta do servidor da adtech precisa incluir um cabeçalho HTTP com o nome Attribution-Reporting-Register-Trigger, que representa as informações sobre um ou mais dos acionadores registrados. O conteúdo do cabeçalho precisa ser codificado em JSON (link em inglês) e incluir os seguintes campos:

Dados do acionador: dados para identificar o evento acionador (três bits para cliques, um bit para visualizações). Precisa ser um número inteiro assinado de 64 bits formatado como uma string.
Prioridade do acionador (opcional): representa a prioridade do acionador em comparação a outros acionadores da mesma fonte de atribuição. Precisa ser um número inteiro assinado com 64 bits formatado como uma string. Para mais detalhes sobre como a prioridade afeta a geração de relatórios, consulte a seção sobre exemplos de priorização.
Chave de eliminação de duplicação (opcional): usada para identificar casos em que o mesmo acionador é registrado várias vezes pela mesma plataforma de adtech para a mesma fonte de atribuição. Precisa ser um número inteiro assinado de 64 bits formatado como uma string.
Chaves de agregação (opcional): uma lista de dicionários que especifica chaves de agregação e os relatórios que devem ser agregados.
Valores de agregação (opcional): uma lista de valores que contribuem para cada chave.
Filtros (opcional): usados para filtrar seletivamente acionadores ou dados de acionadores. Para mais detalhes, consulte a seção Filtros de acionador nesta página.

A resposta do servidor de adtech pode incluir outros dados no cabeçalho Redirecionamentos do relatório de atribuição. Os dados contêm URLs de redirecionamento para que várias adtechs possam registrar uma solicitação.

Diversas adtechs podem registrar o mesmo evento acionador usando redirecionamentos no campo Attribution-Reporting-Redirect ou várias chamadas para o método registerTrigger(). Recomendamos usar o campo da chave de eliminação de duplicação para evitar incluir acionadores duplicados nos relatórios, caso uma mesma adtech forneça várias respostas para um único evento acionador. Saiba mais sobre como e quando usar uma chave de eliminação de duplicação.

O guia para desenvolvedores inclui exemplos de como aceitar o registro de acionadores.

As etapas abaixo mostram um exemplo de fluxo de trabalho.

O SDK de adtechs chama a API para registrar o acionador usando um URI pré-registrado. Consulte Registrar uma conta do Sandbox de privacidade para mais informações.
```
registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
```
A API faz uma solicitação para https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

O servidor HTTPS dessa adtech responde com cabeçalhos contendo o seguinte:

Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1122",
    // This returns 010 for click-through conversions (CTCs) and 0 for
    // view-through conversions (VTCs) in reports
    "priority": "3",
    "deduplication_key": "3344"
    }],
}
Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567

A API faz uma solicitação para cada URL especificado em Attribution-Reporting-Redirect. Neste exemplo, somente um URL é especificado, então a API faz uma solicitação para https://adtechpartner.example?app_install=567.
O servidor HTTPS dessa adtech responde com cabeçalhos contendo o seguinte:
```
Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}
```
Dois acionadores são registrados com base nas solicitações das etapas anteriores.

Recursos de atribuição

As seções abaixo explicam como a API Attribution Reporting faz a correspondência dos acionadores com as fontes de atribuição.

Aplicação do algoritmo de atribuição com prioridade de fonte

A API Attribution Reporting usa um algoritmo de atribuição com prioridade de fonte para fazer a correspondência entre um acionador (conversão) e uma fonte de atribuição.

Os parâmetros de prioridade fornecem maneiras de personalizar a atribuição de acionadores a fontes:

É possível atribuir acionadores a determinados eventos de anúncios. Por exemplo, é possível dar mais ênfase a cliques em vez de visualizações ou focar em eventos de determinadas campanhas.
É possível configurar a fonte de atribuição e o acionador para ter maior probabilidade de receber os relatórios mais importantes ao atingir as limitações de taxa. Por exemplo, você pode garantir que as conversões que recebem lances ou as de alto valor tenham mais chances de aparecer nesses relatórios.

Em casos em que várias plataformas de adtechs registram uma mesma fonte de atribuição, conforme descrito mais adiante nesta página, a atribuição ocorre de maneira independente. Em cada adtech, a fonte de atribuição com maior prioridade é atribuída ao evento acionador. Caso haja várias fontes de atribuição com a mesma prioridade, a API escolhe a última fonte registrada. Qualquer outra fonte de atribuição que não seja selecionada é descartada e não pode ser usada para atribuição a eventos acionadores futuros.

Filtros de acionador

Os registros de fonte e de acionadores incluem outras funcionalidades opcionais para fazer o seguinte:

Filtrar seletivamente e ignorar alguns acionadores.
Escolher os dados do acionador para os relatórios de eventos com base nos dados da fonte.
Excluir um acionador dos relatórios de eventos.

Para filtrar os acionadores de forma seletiva, a adtech pode especificar dados de filtro, compostos de chaves e valores, durante o registro de fonte e acionador. Se a mesma chave for especificada para a fonte e o acionador, ele vai ser ignorado se a intersecção estiver vazia. Por exemplo, uma fonte pode especificar "product": ["1234"], em que product é a chave do filtro e 1234 é o valor. Se o filtro do acionador for definido como "product": ["1111"], o acionador vai ser ignorado. Se não houver nenhuma chave de filtro de acionador correspondente a product, os filtros vão ser ignorados.

Outro cenário em que as plataformas de adtech podem querer filtrar seletivamente os acionadores é forçar uma janela de expiração mais curta. No registro do acionador, uma adtech pode especificar (em segundos) uma janela de lookback de quando a conversão aconteceu. Por exemplo, uma janela de lookback de sete dias é definida como: "_lookback_window": 604800 // 7d

Para decidir se um filtro corresponde, a API verifica primeiro a janela de lookback. Se disponível, a duração desde que a fonte foi registrada precisa ser menor ou igual à duração da janela de lookback.

As plataformas de adtech também podem escolher dados do acionador com base nos dados de evento da fonte. Por exemplo, source_type é gerado automaticamente pela API como navigation ou event. Durante o registro do acionador, trigger_data pode ser definido como um valor para "source_type": ["navigation"] e como um valor diferente para "source_type": ["event"].

Os acionadores vão ser excluídos dos relatórios de eventos se uma das condições abaixo for verdadeira:

trigger_data não foi especificado.
A fonte e o acionador especificam a mesma chave de filtro, mas os valores não são correspondentes. Nesse caso, o acionador é ignorado para relatórios agregáveis e de eventos.

Atribuição após a instalação

Em alguns casos, após a instalação, é necessário atribuir acionadores à mesma fonte de atribuição que gerou a instalação, mesmo que haja outras fontes de atribuição qualificadas que tenham ocorrido mais recentemente.

A API oferece suporte a esse caso de uso, permitindo que as adtechs definam um período de atribuição após a instalação:

Ao registrar uma fonte de atribuição, especifique uma janela em que as instalações são esperadas. Esse período geralmente tem uma duração de dois a sete dias, com um intervalo aceito de um a 30 dias. Especifique esse período em segundos.
Ao registrar uma fonte de atribuição, especifique uma janela de exclusividade em que todos os eventos acionadores pós-instalação vão ser associados à fonte que gerou a instalação. Esse período geralmente tem duração de 7 a 30 dias, com um intervalo aceito de 0 a 30 dias. Especifique esse período em segundos.
A API Attribution Reporting valida quando uma instalação do app acontece e a atribui internamente à fonte de atribuição priorizada. No entanto, a instalação não é enviada a adtechs e não é considerada na respectiva limitação de taxa das plataformas.
A validação da instalação está disponível para todos os apps transferidos por download.
Os acionadores futuros que ocorrerem na janela de atribuição pós-instalação vão ser atribuídos à mesma fonte de atribuição que a instalação validada, desde que essa fonte seja qualificada.

No futuro, podemos tentar ampliar o design para oferecer suporte a modelos de atribuição mais avançados.

A tabela abaixo mostra um exemplo de como as adtechs podem usar a atribuição após a instalação. Todos os acionadores e as fontes de atribuição são registrados pela mesma rede de adtech, e todas as prioridades são as mesmas.

Evento	Dia em que o evento ocorre	Observações
Clique 1	1	A `install_attribution_window` é definida como `172800` (2 dias) e a `post_install_exclusivity_window` como `864000` (10 dias)
Instalação verificada	2	A API atribui internamente as instalações verificadas, mas elas não são consideradas acionadores. Portanto, nenhum relatório é enviado.
Acionador 1 (primeiro acesso)	2	Primeiro acionador registrado pela adtech. Neste exemplo, ele representa um primeiro acesso, mas pode ser qualquer tipo de acionador. Atribuído ao Clique 1 (corresponde à atribuição da instalação verificada).
Clique 2	4	Usa os mesmos valores para `install_attribution_window` e `post_install_exclusivity_window` que o Clique 1
Acionador 2 (pós-instalação)	5	Segundo acionador registrado pela adtech. Neste exemplo, ele representa uma conversão pós-instalação, como uma compra. Atribuído ao Clique 1 (corresponde à atribuição da instalação verificada). O Clique 2 é descartado e não está qualificado para atribuições futuras.

A lista abaixo apresenta algumas observações sobre a atribuição pós-instalação:

Se a instalação verificada não acontecer dentro do número de dias especificado por install_attribution_window, a atribuição pós-instalação não vai ser aplicada.
As instalações verificadas não são registradas por adtechs e não são enviadas nos relatórios. Elas não são contabilizadas nos limites de taxa de uma adtech. As instalações verificadas são usadas apenas para identificar a fonte de atribuição responsável pela instalação.
No exemplo da tabela anterior, os acionadores 1 e 2 representam o primeiro acesso e a conversão pós-instalação, respectivamente. No entanto, as plataformas de adtech podem registrar qualquer tipo de acionador. Em outras palavras, o primeiro acionador não precisa ser de primeiro acesso.
Se mais acionadores forem registrados depois que a post_install_exclusivity_window expirar, o clique 1 ainda vai estar qualificado para a atribuição, desde que não tenha expirado nem atingido as limitações de taxa.
- O clique 1 ainda poderá ser descartado se uma fonte de atribuição de prioridade mais alta for registrada.
Se o app do anunciante for desinstalado e reinstalado, a reinstalação vai ser contada como uma nova instalação verificada.
Se o clique 1 for um evento de visualização, os acionadores de "primeiro acesso" e pós-instalação ainda vão ser atribuídos a ele. A API restringe a atribuição a um acionador por visualização, exceto no caso de pós-instalação, em que são permitidos até dois por visualização. No caso de atribuição pós-instalação, as adtechs podem receber duas janelas diferentes para geração de relatórios (dois dias depois ou na data de vencimento da fonte).

Suporte a todas as combinações de caminhos de acionadores baseados na Web e no app

A API Attribution Reporting 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 encontra 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 encontra 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 encontra um anúncio em um navegador de um app ou para dispositivos móveis e realiza uma conversão nesse navegador ou em outro no mesmo dispositivo.

Permitimos que navegadores da Web ofereçam suporte às novas funcionalidades expostas pela Web, por exemplo, uma funcionalidade semelhante ao Sandbox de privacidade da API Attribution Reporting da Web (link em inglês), que pode chamar as APIs do Android para ativar a atribuição em apps e na Web.

Saiba mais sobre as mudanças que as adtechs e os apps precisam fazer para oferecer suporte a caminhos de acionadores para medição entre apps e na Web.

Priorizar vários acionadores para uma única fonte de atribuição

Uma única fonte de atribuição pode levar a vários acionadores. Por exemplo, um fluxo de compra pode envolver um acionador de "instalação do app", um ou mais acionadores "adicionar ao carrinho" e um acionador "comprar". Cada acionador é atribuído a uma ou mais fontes de atribuição, de acordo com o algoritmo de atribuição com prioridade de fonte, descrito mais adiante nesta página.

Existem limites para quantos acionadores podem ser atribuídos a uma única fonte. Para mais detalhes, leia o trecho sobre como acessar dados de medição em relatórios de atribuição mais adiante nesta página. Em casos em que existem vários acionadores excedendo esses limites, é útil introduzir a lógica de priorização para extrair os mais importantes. Por exemplo, os desenvolvedores de uma adtech podem querer priorizar o recebimento de acionadores de "compra" em vez de acionadores "adicionar ao carrinho".

Para oferecer suporte a essa lógica, um campo de prioridade separado pode ser definido no acionador. Assim, os acionadores com maior prioridade vão ser escolhidos antes da aplicação dos limites, dentro de uma determinada janela de geração de relatórios.

Permitir que várias adtechs registrem acionadores ou fontes de atribuição

É comum que mais de uma adtech receba relatórios de atribuição, geralmente para eliminar a duplicação em várias redes. Por isso, a API permite que várias adtechs registrem o mesmo acionador ou a mesma fonte de atribuição. Uma adtech precisa registrar as fontes de atribuição e os acionadores para receber postbacks da API. A atribuição é feita entre as fontes e os acionadores registrados pela adtech.

Os anunciantes que quiserem terceirizar a eliminação de duplicação de várias redes podem fazer isso usando uma técnica semelhante a esta:

Configurar um servidor interno para registrar e receber relatórios da API.
Continuar usando um parceiro de medição para dispositivos móveis.

Fontes de atribuição

Os redirecionamentos da fonte de atribuição podem ser usados com o método registerSource():

A adtech que chama o método registerSource() pode fornecer um campo Attribution-Reporting-Redirect extra na resposta, que representa o conjunto de URLs de redirecionamento da adtech do parceiro.
A API chama os URLs de redirecionamento para que a fonte de atribuição seja registrada pelas adtechs parceiras.

Vários URLs de adtechs parceiras podem ser listados no campo Attribution-Reporting-Redirect, e essas parceiras não podem especificar o próprio campo Attribution-Reporting-Redirect.

A API também permite diferentes adtechs para cada chamada de registerSource().

Acionadores

Terceiros podem registrar acionadores de maneira semelhante: as adtechs podem usar o campo Attribution-Reporting-Redirect extra ou os dois podem chamar o método registerTrigger().

Quando um anunciante usa várias adtechs para registrar o mesmo evento acionador, é necessário usar uma chave de eliminação de duplicação. Essa chave serve para remover qualquer ambiguidade de relatórios repetidos sobre o mesmo evento registrado pela mesma plataforma de adtech. Por exemplo, uma adtech pode fazer com que o SDK chame a API diretamente para registrar um acionador e colocar o URL dela no campo de redirecionamento da chamada de outra adtech. Caso nenhuma chave de eliminação de duplicação seja fornecida, é possível que acionadores duplicados sejam informados como eventos únicos para cada adtech.

Gerenciar acionadores duplicados

Uma adtech pode registrar o mesmo acionador várias vezes com a API. Os cenários incluem o seguinte:

O usuário realiza a mesma ação (acionador) várias vezes. Por exemplo, o usuário procura o mesmo produto várias vezes na mesma janela de relatórios.
O app do anunciante usa vários SDKs para a medição de conversões, que são redirecionados para a mesma adtech. Por exemplo, esse app usa dois parceiros de medição: MMP 1 e MMP 2. Os dois MMPs redirecionam para a adtech 3. Quando há um acionador, os MMPs o registram com a API Attribution Reporting. Então, a adtech 3 recebe dois redirecionamentos separados, um do MMP 1 e outro do MMP 2, para o mesmo acionador.

Nesses casos, há várias maneiras de suprimir relatórios de eventos em acionadores duplicados para diminuir a probabilidade de exceder os limites de taxa aplicados aos relatórios de eventos. A maneira recomendada é usar uma chave de eliminação de duplicação.

Método recomendado: chave de eliminação de duplicação

O método recomendado é que o app do anunciante transmita uma chave de eliminação de duplicação exclusiva para qualquer adtech ou SDK usado para a medição de conversões. Quando ocorre uma conversão, o app transmite uma chave de eliminação de duplicação para a adtech ou os SDKs. Essas adtechs ou SDKs continuam transmitindo a chave de eliminação de duplicação para redirecionamentos usando um parâmetro nos URLs especificados em Attribution-Reporting-Redirect.

As adtechs podem optar por registrar apenas o primeiro acionador com uma determinada chave de eliminação de duplicação, vários acionadores ou todos eles. Elas podem especificar a deduplication_key ao registrar acionadores duplicados.

Se uma adtech registrar vários acionadores com a mesma chave de eliminação de duplicação e fonte atribuída, somente o primeiro registrado vai ser enviado nos relatórios de eventos. Os acionadores duplicados ainda vão ser enviados em relatórios agregáveis criptografados.

Método alternativo: as adtechs definem os tipos de acionador de acordo com o anunciante

Nos casos em que as adtechs não querem usar a chave de eliminação de duplicação ou em que o app do anunciante não pode transmitir essa chave, há uma alternativa. Todas as conversões de medição das adtechs de um determinado anunciante precisam trabalhar juntas para definir diferentes tipos de acionadores para cada anunciante.

As adtechs que iniciam a chamada de registro do acionador (por exemplo, SDKs) incluem um parâmetro em URLs especificados em Attribution-Reporting-Redirect, como duplicate_trigger_id. Esse parâmetro duplicate_trigger_id pode incluir informações como o nome do SDK e o tipo de acionador desse anunciante. As adtechs podem enviar um subconjunto desses acionadores duplicados para relatórios de eventos. Elas também podem incluir esse duplicate_trigger_id nas chaves de agregação.

Exemplo de atribuição de várias redes

No exemplo descrito nesta seção, o anunciante usa duas plataformas de adtech de veiculação (Adtech A e Adtech B) e um parceiro de medida (MMP).

Para começar, a Adtech A, a Adtech B e o MMP precisam se registrar para usar a API Attribution Reporting. Consulte Registrar uma conta do Sandbox de privacidade para mais informações.

A lista abaixo fornece uma série hipotética de ações do usuário que ocorrem em cada dia e mostra como a API Attribution Reporting processa essas ações em relação à Adtech A, à Adtech B e ao MMP:

Dia 1: o usuário clica em um anúncio veiculado pela Adtech A

A Adtech A chama registerSource() com o URI dela. A API faz uma solicitação ao URI, e o clique é registrado com os metadados da resposta do servidor da Adtech A.

A Adtech A também inclui o URI do MMP no cabeçalho Attribution-Reporting-Redirect. A API faz uma solicitação ao URI do MMP, e o clique é registrado com os metadados da resposta do servidor do MMP.

Dia 2: o usuário clica em um anúncio veiculado pela Adtech B

A Adtech B chama registerSource() com o URI dela. A API faz uma solicitação ao URI, e o clique é registrado com os metadados da resposta do servidor da Adtech B.

Assim como a Adtech A, a Adtech B também incluiu o URI do MMP no cabeçalho Attribution-Reporting-Redirect. A API faz uma solicitação ao URI do MMP, e o clique é registrado com os metadados da resposta do servidor do MMP.

Dia 3: o usuário encontra um anúncio veiculado pela Adtech A

A API responde da mesma maneira que no dia 1, com a exceção de que uma visualização é registrada para a Adtech A e o MMP.

Dia 4: o usuário instala o app, que usa o MMP para medir a conversão

O MMP chama registerTrigger() com o URI dele. A API faz uma solicitação ao URL, e a conversão é registrada com os metadados da resposta do servidor do MMP.

O MMP também inclui os URIs da Adtech A e da Adtech B no cabeçalho Attribution-Reporting-Redirect. A API faz solicitações aos servidores da Adtech A e da Adtech B, e a conversão é registrada de acordo com os metadados das respostas do servidor.

O diagrama a seguir ilustra o processo descrito na lista anterior:

Exemplo de como a API Attribution Reporting responde a uma série de ações do usuário.

A atribuição funciona desta maneira:

A Adtech A define a prioridade de cliques como mais alta que as visualizações e recebe a instalação atribuída ao clique no dia 1.
A Adtech B recebe a instalação atribuída no dia 2.
O MMP define a prioridade dos cliques como mais alta que a das visualizações e recebe a instalação atribuída ao clique no dia 2. O clique do dia 2 é o evento de anúncio mais recente e com maior prioridade.

Atribuição de várias redes sem redirecionamentos

O uso de redirecionamentos para permitir que várias adtechs registrem fontes de atribuição e acionadores é recomendado, mas pode haver casos em que isso não é viável. Esta seção detalha como oferecer suporte a atribuição de várias redes sem redirecionamentos.

Fluxo de alto nível

No registro da fonte, a rede adtech que veicula os anúncios compartilha as chaves de agregação.
No registro do acionador, o anunciante ou parceiro de medição escolhe quais partes da chave da fonte vão ser usadas e especifica a configuração de atribuição delas.
A atribuição é baseada na configuração de atribuição, nas chaves compartilhadas e em todas as fonte que foram registradas por esse anunciante ou parceiro de avaliação (por exemplo, de outra rede de adtech de veiculação que ativou redirecionamentos).
Se o acionador for atribuído a uma fonte de uma adtech de veiculação sem redirecionamento, o anunciante ou parceiro de medição poderá receber um relatório agregável que combina as partes das chaves de fonte e acionador definidas na etapa 2.

Registro da fonte

No registro de fonte, a rede de adtech que veicula os anúncios pode escolher compartilhar as chaves de agregação da fonte ou um subconjunto delas, em vez de redirecionar. A adtech de veiculação não precisa usar essas chaves da fonte nos relatórios agregáveis e pode declará-las somente em nome do anunciante ou do parceiro de medição, se necessário.

As chaves de agregação compartilhadas estão disponíveis para qualquer adtech que registre um acionador para o mesmo anunciante. No entanto, cabe à adtech de veiculação e à de medição do acionador colaborar sobre quais tipos de chave de agregação são necessários, os nomes deles e como decodificar as chaves em dimensões legíveis.

Registro do acionador

No registro do acionador, a adtech de medição escolhe quais partes da chave da fonte são aplicadas a cada chave do acionador, incluindo as compartilhadas pelas adtechs de veiculação.

Além disso, a adtech de medição também precisa especificar a lógica de atribuição de hierarquia usando uma nova chamada da API de configuração de atribuição. Nessa configuração, a adtech pode especificar a prioridade, a expiração e os filtros das fontes que não estavam visíveis, como fontes que não usavam um redirecionamento.

Atribuição

A API Attribution Reporting realiza a atribuição de último toque, que tem prioridade de fonte, para a adtech de medição com base na configuração de atribuição, nas chaves compartilhadas e nas fontes registradas. Por exemplo:

O usuário clicou em anúncios veiculados pelas adtechs A, B, C e D. Em seguida, ele instalou o app do anunciante, que usa uma adtech parceira de de medição (MMP, na sigla em inglês).
A Adtech A redireciona as fontes dela para o MMP.
As Adtechs B e C não redirecionam, mas compartilham as chaves de agregação.
A Adtech D não redireciona nem compartilha chaves de agregação.

O MMP registra uma fonte da Adtech A e define uma configuração de atribuição que inclui a Adtech B e a Adtech D.

A atribuição do MMP agora inclui o seguinte:

A Adtech A, já que o MMP registrou uma fonte no redirecionamento dessa adtech.
A Adtech B, já que ela compartilhou chaves, e o MMP a incluiu na configuração de atribuição.

A atribuição do MMP não inclui o seguinte:

A Adtech C, já que o MMP não a incluiu na configuração de atribuição.
A Adtech D, já que não redirecionou nem compartilhou chaves de agregação.

Depuração

Para oferecer suporte à depuração da atribuição de várias redes sem redirecionamentos, um campo extra, shared_debug_key, está disponível para a definição de adtechs. registro de origem. Se definido no registro da fonte original, ele também será definido na fonte derivada correspondente como debug_key durante o registro do acionador para a atribuição de várias redes sem redirecionamentos. Essa chave de depuração está anexada como source_debug_key nos relatórios agregados e de eventos.

Esse recurso de depuração só tem suporte para atribuição de várias redes sem redirecionamentos nos seguintes cenários:

Medição de app para app em que o ID de publicidade está permitido
Medição de app para Web em que o ID de publicidade é permitido e correspondente na fonte do app e no acionador da Web.
Medição da Web para a Web (na mesma app do navegador) quando ar_debug` está presente na origem e no acionador.

Descoberta de chaves para atribuição em várias redes sem redirecionamentos

A descoberta de chaves visa simplificar como as adtechs (geralmente MMPs) implementam a configuração de atribuição para fins de atribuição em várias redes quando uma ou várias adtechs estão usando chaves de agregação compartilhadas, conforme descrito em Atribuição de várias redes sem redirecionamentos acima.

Quando um MMP consulta o serviço de agregação para gerar relatórios de resumo das campanhas que incluem origens derivadas, esse serviço exige que o MMP especifique a lista de chaves possíveis como entrada para o job de agregação. Em alguns casos, a lista de possíveis chaves de agregação de origem pode ser muito grande ou desconhecida. Grandes listas de possíveis chaves são difíceis de rastrear e também podem ser bastante complexas e de alto custo de processamento. Confira estes exemplos:

A lista de todas as chaves possíveis é grande:
- Uma rede de publicidade veiculada está executando uma iniciativa complexa de aquisição de usuários que inclui 20 campanhas, cada uma com 10 grupos de anúncios, e cada grupo de anúncios com cinco criativos que são atualizados semanalmente com base na performance.
A lista de todas as chaves possíveis é desconhecida:
- Uma rede de publicidade está veiculando anúncios em vários apps para dispositivos móveis, em que a lista completa de IDs do app do editor não é conhecida no lançamento da campanha.
- Um anunciante está trabalhando em várias redes de publicidade veiculadas que não estão redirecionando para o MMP no registro de origem. Cada rede de publicidade veiculada tem uma estrutura e valores de chave diferentes, que podem não ser compartilhados antecipadamente com o MMP.

Com a introdução da descoberta de chaves:

O serviço de agregação não exige mais uma enumeração completa de possíveis chaves de agregação.
Em vez de especificar a lista completa de chaves possíveis, um MMP pode criar um conjunto de chaves vazio (ou parcialmente vazio) e definir um limite, para que apenas chaves (não pré-declaradas) com valores acima o limite sejam incluídas na saída.
O MMP recebe um relatório de resumo que inclui valores com ruído para chaves que têm valores de contribuição acima do limite definido. O relatório também pode incluir chaves que não têm contribuições de usuários reais associadas e são puramente ruídos.
O MMP usa o campo x_network_bit_mapping no registro de acionadores para determinar qual adtech corresponde a qual chave.
O MMP pode entrar em contato com a adtech apropriada para entender os valores na chave de origem.

Em resumo, a descoberta de chaves permite que as MMPs recebam chaves de agregação sem conhecê-las com antecedência, evitando o processamento de um grande volume de chaves de origem em detrimento do ruído.

Redirecionamentos em cadeia

Ao fornecer vários cabeçalhos Attribution-Reporting-Redirect em uma fonte ou acionar o registro HTTPS do servidor-resposta, uma adtech poderá usar o API Reporting para realizar vários registros de origem e acionador com um único de registro da API.

Na resposta do servidor, a adtech também pode incluir um único cabeçalho Location (redirecionamento 302) com um URL, que, por sua vez, leva a outro registro, até um limite definido.

Ambos os tipos de cabeçalho são opcionais e nenhum pode ser fornecido se os redirecionamentos forem não são necessários. Um ou ambos os tipos de cabeçalho podem ser fornecidos. As solicitações de registro de origem e acionador (incluindo redirecionamentos) são tentadas novamente em caso de falha de rede. O número de novas tentativas por solicitação é limitado a um número fixo para evitar um impacto significativo no dispositivo.

Os redirecionamentos não são aceitos para registerWebSource e registerWebTrigger usados por navegadores. Confira mais detalhes na página Visão geral Guia de implementação.

Acessar dados de medição em relatórios de atribuição

A API Attribution Reporting permite os tipos de relatórios apresentados abaixo, que são descritos em mais detalhes posteriormente nesta página:

Os relatórios de eventos associam uma fonte de atribuição específica (clique ou visualização) a bits limitados de dados dos acionadores de alta fidelidade.
Os relatórios agregáveis não são necessariamente vinculados a uma fonte de atribuição específica. Esses relatórios fornecem dados de acionadores com mais informações e maior fidelidade que os relatórios de evento. Contudo, esses dados só estão disponíveis de maneira agregada.

Esses dois tipos de relatório são complementares e podem ser usados simultaneamente.

Relatórios de eventos

Depois que um acionador é atribuído a uma fonte de atribuição, um relatório de eventos é gerado e armazenado no dispositivo até que possa ser enviado ao URL de postback de cada adtech durante um dos períodos para envio de relatórios descritos em mais detalhes posteriormente nesta página.

Os relatórios de eventos são úteis quando poucas informações sobre o acionador são necessárias. Os dados do acionador a nível de evento são limitados a três bits de dados para cliques, o que significa que um acionador pode ser atribuído a uma entre oito categorias, e um bit para visualizações. Além disso, os relatórios de evento não oferecem suporte à codificação de dados do acionador de alta fidelidade, como um preço específico ou o momento de acionamento. Como a atribuição acontece no dispositivo, não há suporte para análise entre dispositivos nos relatórios de evento.

O relatório de evento contém os dados abaixo:

Destino: nome do pacote do app do anunciante ou o eTLD+1 em que o acionamento ocorreu
ID de fonte de atribuição: o mesmo ID de fonte de atribuição usado para registrar uma fonte de atribuição.
Tipo de acionador: um ou três bits de dados de acionador de baixa fidelidade, dependendo do tipo de fonte de atribuição

Mecanismos de preservação de privacidade aplicados a todos os relatórios

Os limites a seguir são aplicados depois que prioridades relacionadas a acionadores e fontes de atribuição são consideradas.

Limites para o número de adtechs

Existem limites para o número de adtechs que podem registrar ou receber relatórios da API. A proposta atual é:

100 adtechs com fontes de atribuição por {app de origem, app de destino, 30 dias, dispositivo}.
10 adtechs com acionadores atribuídos por {app de origem, app de destino, 30 dias, dispositivo}.
20 adtechs podem registrar uma única fonte de atribuição ou um único acionador (usando Attribution-Reporting-Redirect).

Limites para o número de destinos exclusivos

Esses limites dificultam a colaboração de um conjunto de adtechs, consultando um grande número de apps para entender o comportamento de uso de determinado usuário.

Em todas as fontes registradas e em todas as adtechs, a API oferece suporte a no máximo 200 destinos exclusivos por app de origem, por minuto.
Em todos os canais registrados para uma única adtech, a API oferece suporte a no máximo 50 por app de origem, por minuto. Esse limite impede que uma adtech use todo o orçamento acima do limite de taxa mencionado anteriormente.

Origens expiradas não contam para os limites de taxa.

Uma origem de relatórios por app de fonte por dia

Uma plataforma de adtech só pode usar uma origem de relatórios para registrar fontes em um app de editor em um determinado dispositivo no mesmo dia. Esse limite de taxa impede que as adtechs usem várias origens de relatórios para acessar mais orçamento de privacidade.

Considere o seguinte cenário, em que uma única adtech quer usar várias origens de relatórios para registrar fontes em um app de editor em um único dispositivo.

A origem de relatórios 1 da Adtech A registra uma fonte no App B.
12 horas depois, a origem de relatórios 2 da Adtech A tenta registrar uma fonte no App B.

A segunda fonte, para a origem de relatórios 2 da Adtech A, seria rejeitada pela API. A origem de relatórios 2 da Adtech A não consegue registrar uma fonte no mesmo dispositivo no App B até o dia seguinte.

Período de espera e limitações de taxa

Para limitar a quantidade de vazamentos de identidades de usuários entre um par {origem, destino}, a API limita a quantidade total de informações enviadas por um usuário em determinado período.

A proposta atual é limitar cada adtech a 100 acionadores atribuídos por {app de origem, app de destino, 30 dias, dispositivo}.

Número de destinos exclusivos

A API limita o número de destinos que uma adtech pode tentar medir. Quanto mais baixo o limite, mais dificuldade a adtech vai ter no uso da API para tentar medir a atividade de navegação do usuário que não esteja associada a anúncios mostrados.

A proposta atual é limitar cada adtech a 100 destinos diferentes com fontes não expiradas por app de origem.

Mecanismos de preservação de privacidade aplicados a relatórios de eventos

Fidelidade limitada dos dados do acionador

A API oferece um bit para acionadores de visualização completa e três bits para acionadores de clique. As fontes de atribuição continuam tendo suporte a 64 bits de metadados.

Avalie se é possível reduzir as informações expressas nos acionadores e como fazer isso para que eles funcionem com o número limitado de bits disponíveis nos relatórios de evento.

Framework para ruídos de privacidade diferencial

Um dos objetivos dessa API é permitir que as métricas de evento atendam aos requisitos de privacidade diferencial locais usando respostas k-aleatórias a fim de gerar um resultado com ruído para cada evento de origem.

O ruído é aplicado caso um evento de atribuição de fonte seja relatado de maneira verdadeira. Uma fonte de atribuição é registrada no dispositivo com probabilidade $ 1-p $ de que a fonte seja registrada normalmente e probabilidade de $ p $ de que o dispositivo escolha aleatoriamente entre todos os estados resultantes possíveis da API, o que inclui não relatar nada ou gerar vários relatórios falsos.

A resposta k-aleatória é um algoritmo que é particular com diferencial de épsilon se a equação abaixo for atendida:

\[ p = \frac{k}{k + e^ε - 1} \]

Para valores de ε baixos, o resultado verdadeiro é protegido pelo mecanismo de resposta k-aleatória. Os parâmetros de ruído exatos estão em fase de desenvolvimento e estão sujeitos a mudanças com base nos feedbacks recebidos. A proposta atual é de:

p=0,24% para fontes de navegação.
p=0,00025% para fontes de eventos.

Limites de acionadores disponíveis (conversões)

Existem limites para o número de acionadores por fonte de atribuição. A proposta atual é esta:

Um ou dois acionadores para fontes de atribuição de visualização de anúncio (dois acionadores disponíveis somente no caso da atribuição pós-instalação)
Três acionadores para fontes de atribuição de cliques em anúncios

Períodos específicos para enviar relatórios (comportamento padrão)

Os relatórios de eventos das fontes de atribuição de visualização de anúncio são enviados uma hora após a fonte expirar. A validade pode ser configurada, mas não pode ser menor que um dia nem maior que 30 dias. Se dois acionadores forem atribuídos a uma fonte de atribuição de visualização de anúncio (pela atribuição pós-instalação), os relatórios de eventos poderão ser enviados nos intervalos de janela de relatórios especificados da seguinte maneira.

Os relatórios de eventos sobre fontes de atribuição de cliques nos anúncios não podem ser configurados e são enviados antes do fim da validade ou nessa data em períodos específicos em relação ao momento em que a fonte foi registrada. O tempo entre o registro da fonte de atribuição e o vencimento é dividido em várias janelas de relatórios. Cada janela de relatórios tem um prazo, contado a partir do momento de registro da fonte de atribuição. Ao fim de cada janela de relatórios, o dispositivo coleta todos os acionadores que ocorreram desde a janela anterior e envia um relatório agendado. A API oferece suporte às janelas de geração de relatórios abaixo:

Dois dias: o dispositivo coleta todos os acionadores que ocorreram dentro de um período de no máximo dois dias desde o registro da fonte de atribuição. O relatório é enviado dois dias e uma hora após o momento do registro da fonte de atribuição.
Sete dias: o dispositivo coleta todos os acionadores que ocorreram dentro de um período de dois a sete dias desde o registro da fonte de atribuição. O relatório é enviado sete dias e uma hora após o momento do registro da fonte de atribuição.
Duração personalizada, definida pelo atributo "expiry" (validade) de uma fonte de atribuição. O relatório é enviado uma hora após o prazo de validade especificado. Esse valor não pode ser menor que um dia nem maior que 30 dias.

Configuração flexível no nível do evento

A configuração padrão para relatórios de eventos é a recomendada para adtechs quando iniciarem os testes utilitários, mas pode não ser ideal para todos os casos de uso. A API Attribution Reporting vai oferecer suporte a configurações opcionais e mais flexíveis para que as adtechs tenham mais controle sobre a estrutura dos relatórios de eventos e possam maximizar a utilidade dos dados.

Essa flexibilidade adicional será introduzida na API Attribution Reporting em duas fases:

Fase 1: configuração flexível no nível do evento
- Essa versão fornece um subconjunto de recursos completos e pode ser usada independentemente da fase 2.
Fase 2: versão completa da configuração flexível no nível do evento

A Fase 1 (nível de evento flexível do Lite) pode ser usada para:

variar a frequência dos relatórios especificando o número de janelas;
variar o número de atribuições por registro de fonte;
reduzir a quantidade total de ruído diminuindo os parâmetros acima;
configurar janelas de relatórios em vez de usar os valores padrão.

A Fase 2 (nível de evento totalmente flexível) pode ser usada para realizar todas as capacidades da Fase 1 e:

variar a cardinalidade dos dados do acionador em um relatório;
reduzir a quantidade total de ruído diminuindo a cardinalidade dos dados do acionador.

A redução de uma dimensão da configuração padrão permite que a adtech aumente outra dimensão. Como alternativa, a quantidade total de ruído em um relatório de eventos pode ser reduzida com a diminuição líquida dos parâmetros mencionados acima.

Além de definir dinamicamente os níveis de ruído com base na configuração escolhida por uma adtech, teremos alguns limites de parâmetros para evitar grandes custos de processamento e configurações com muitos estados de saída (em que o ruído vai aumentar consideravelmente). Confira um exemplo de conjunto de restrições. Incentivamos o envio de feedback sobre a [proposta de design][50]:

Máximo de 20 relatórios no total, globalmente e por trigger_data
Máximo de cinco janelas de relatórios possíveis por trigger_data
Máximo de 32 cardinalidades de dados de acionadores (não aplicável para a Fase 1: nível de evento flexível do Lite)

Conforme as adtechs começam a usar esse recurso, saiba que o uso de valores extremos pode resultar em uma grande quantidade de ruído ou em falha no registro caso os níveis de privacidade não sejam atendidos.

Relatórios agregáveis

Antes de usar os relatórios agregáveis, configure sua conta na nuvem e comece a receber esses relatórios.

Relatórios agregáveis fornecem com mais rapidez dados de acionador de maior fidelidade com origem no dispositivo, como complemento aos dados oferecidos pelos relatórios de evento. Esses dados de maior fidelidade só podem ser observados de forma agregada e não ficam associados a um acionador ou usuário específico. As chaves de agregação têm até 128 bits, o que permite que os relatórios agregáveis ofereçam suporte a casos de uso de geração de relatórios, como estes:

Relatórios de valores de acionadores, como receita
Processamento de mais tipos de acionadores

Além disso, os relatórios agregáveis usam a mesma lógica de atribuição com prioridade de fonte que os relatórios de evento, mas oferecem suporte a mais conversões atribuídas a um clique ou visualização.

O design geral da maneira como a API Attribution Reporting prepara e envia relatórios agregáveis, mostrados no diagrama, é este:

O dispositivo envia relatórios agregáveis criptografados para as adtechs. Em um ambiente de produção, as adtechs não podem usar esses relatórios diretamente.
A adtech envia um lote de relatórios agregáveis para o serviço de agregação.
O serviço de agregação lê um lote de relatórios agregáveis e, em seguida, descriptografa e agrega esses relatórios.
Os dados agregados finais são enviados de volta à adtech em um relatório resumido.

Processo usado pela API Attribution Reporting para preparar e enviar relatórios agregados.

Os relatórios agregáveis contêm os dados abaixo relacionados às fontes de atribuição:

Destino: o nome do pacote do app ou o URL da Web eTLD+1 em que o acionador foi ativado.
Data: a data em que o evento representado pela fonte de atribuição ocorreu.
Payload: valores dos acionadores, coletados como pares de chave-valor criptografados, usados no serviço de agregação confiável para calcular as agregações.

Serviços de agregação

Os serviços apresentados abaixo oferecem funcionalidades de agregação e ajudam a proteger contra o acesso indevido a dados de agregação.

Esses serviços são gerenciados por diferentes partes, que são descritas em mais detalhes posteriormente nesta página:

O serviço de agregação é o único que as adtechs precisam implantar.
Os serviços de gerenciamento de chaves e contabilização de relatórios agregáveis são executados por partes confiáveis, chamadas de coordenadores. Esses coordenadores atestam que o código que executa o serviço de agregação é o disponibilizado publicamente pelo Google e que os mesmos serviços de gerenciamento de chaves e contabilização de relatórios agregáveis são aplicados a todos os usuários dos serviços de agregação.

Serviço de agregação

As plataformas de adtech precisam implantar um serviço de agregação antecipadamente, de acordo com os binários fornecidos pelo Google.

Esse serviço de agregação opera em um ambiente de execução confiável (TEE), hospedado na nuvem. Um TEE oferece os benefícios de segurança abaixo:

Ele garante que o código que opera no TEE é o binário específico fornecido pelo Google. A menos que essa condição seja atendida, o serviço de agregação não poderá acessar as chaves de descriptografia que precisa para funcionar.
Ele oferece segurança ao processo em execução, isolando o processo de monitoramento ou adulterações externas.

Esses benefícios de segurança deixam o ambiente mais seguro para que um serviço de agregação possa executar operações confidenciais, como o acesso a dados criptografados.

Para mais informações sobre considerações de design, fluxo de trabalho e segurança do serviço de agregação, consulte a documento do serviço de agregação no GitHub.

Serviço de gerenciamento de chaves

Verifica se um serviço de agregação está executando uma versão aprovada do binário e, em seguida, fornece ao serviço de agregação na adtech as chaves de descriptografia corretas para os dados dos acionadores.

Contabilização de relatórios agregáveis

Esse serviço acompanha a frequência com que o serviço de agregação de uma adtech acessa um acionador específico, que pode conter várias chaves de agregação, e limita o acesso ao número correto de descriptografias. Consulte a proposta do Serviço de agregação da API Attribution Reporting (link em inglês) para mais detalhes.

API Aggregatable Reports

A API para criar contribuições de relatórios agregáveis usa a mesma API base que é utilizada para registrar uma fonte de atribuição em relatórios de evento. As seções abaixo descrevem as extensões da API:

Registrar os dados agregáveis da fonte de atribuição

Quando a API faz uma solicitação para o URI da fonte de atribuição, a adtech pode registrar uma lista de chaves de agregação, com o nome histogram_contributions. Para isso, ela responde com um novo campo chamado aggregation_keys no cabeçalho HTTP Attribution-Reporting-Register-Source, com a chave definida como key_name e o valor como key_piece:

(Chave) Nome da chave: uma string para o nome da chave. Usado como chave de mesclagem para combinar as chaves do lado do acionador e formar a chave final.
(Valor) Parte da chave: um valor de bitstring para a chave.

A chave do bucket de histograma final é totalmente definida no momento da ativação ao executar uma operação binária OR nessas partes e nas partes do acionador.

As chaves finais são restritas a um máximo de 128 bits. As chaves que excedem esse limite ficam truncadas. Isso significa que as strings hexadecimais no JSON precisam ser limitadas a, no máximo, 32 dígitos.

Saiba mais (link em inglês) sobre como as chaves de agregação são estruturadas e como você pode configurá-las.

No exemplo abaixo, uma adtech usa a API para coletar:

contagens de conversões agregadas de uma campanha;
valores de compra agregados de uma área geográfica.

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Registrar o acionador agregável

O registro de acionadores inclui outros dois campos.

O primeiro é usado para registrar uma lista de chaves agregadas no lado do acionador. A adtech precisa responder com o campo aggregatable_trigger_data no cabeçalho HTTP Attribution-Reporting-Register-Trigger, incluindo os campos abaixo para cada chave agregada na lista:

Parte da chave: um valor de bitstring da chave.
Chaves de fonte: uma lista de strings com os nomes das chaves da fonte de atribuição que vão ser combinadas com a chave de acionador para formar as chaves finais.

O segundo campo é usado para registrar uma lista de valores que precisam contribuir com cada chave. A adtech precisa responder com o campo aggregatable_values no cabeçalho HTTP Attribution-Reporting-Register-Trigger. O segundo campo é usado para registrar uma lista de valores que precisam contribuir com cada chave, que podem ser números inteiros no intervalo $ [1, 2^{16}] $.

Cada acionador pode fazer várias contribuições para os relatórios agregáveis. O valor total das contribuições para qualquer evento de fonte é vinculado por um parâmetro $ L1 $, que é a soma máxima das contribuições (valores) em todas as chaves agregadas de uma determinada fonte. $ L1 $ se refere à sensibilidade L1 ou norma das contribuições do histograma por evento de fonte. Exceder esses limites faz com que as contribuições futuras diminuam silenciosamente. A proposta inicial é definir $ L1 $ como $ 2^{16} $ (65536).

O ruído no serviço de agregação é ajustado proporcionalmente a esse parâmetro. Por isso, é recomendável ajustar corretamente os valores informados a uma determinada chave agregada, com base na parte do orçamento de $ L1 $ alocada a ela. Essa abordagem ajuda a garantir que os relatórios agregados mantenham a maior fidelidade possível quando o ruído é aplicado. Esse mecanismo é altamente flexível e oferece suporte a diversas estratégias de agregação.

No exemplo abaixo, o orçamento de privacidade é dividido igualmente entre campaignCounts e geoValue, dividindo a contribuição de $ L1 $ para cada um:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

O exemplo anterior gera estas contribuições do histograma:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Os fatores de escalonamento podem ser invertidos para alcançar os valores corretos do ruído aplicado:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

Privacidade diferencial

Um dos objetivos dessa API é ter um framework que ofereça suporte à medição agregada de privacidade diferencial. Para isso, adicione ruído proporcional ao orçamento de $ L1 $. Você pode escolher o ruído com esta distribuição:

\[ Laplace(\frac{L1}{ε}) \]

Integração das APIs Protected Audience e Attribution Reporting

A integração entre as APIs Protected Audience e Attribution Reporting permite que as adtechs avaliem a performance da atribuição em várias táticas de remarketing para entender quais tipos de público-alvo geram o ROI mais alto.

Com essa integração entre APIs, as adtechs podem:

Criar um mapa de chave-valor de URIs a ser usado para 1) relatórios de interação e 2) registro de origem.
Incluir CustomAudience no mapeamento de atalhos da fonte para relatórios de resumo agregados (usando a API Attribution Reporting).

Quando um anúncio é mostrado ou o usuário clica nele:

O URL usado para informar essas interações usando a API Protected Audience também será usado para registrar uma visualização ou um clique como fonte qualificada com a API Attribution Reporting.
A adtech pode transmitir o objeto CustomAudience (ou outras informações contextuais relevantes sobre o anúncio, como posicionamento ou duração da visualização) usando esse URL. Dessa forma, os metadados podem ser propagados para os relatórios de resumo quando a adtech estiver analisando a performance agregada da campanha.

Para mais informações sobre como isso é ativado na API, consulte a seção relevante da explicação da API Protected Audience.

Exemplos de atribuição, relatórios e prioridade de registro

Este exemplo mostra um conjunto de interações do usuário e como as prioridades de fontes de atribuição e de acionadores definidas pelas adtechs podem afetar os relatórios atribuídos. Neste exemplo, pressupomos o seguinte:

Todos os acionadores e fontes de atribuição são registrados pela mesma adtech e para o mesmo anunciante.
Todos os acionadores e fontes de atribuição estão acontecendo durante a primeira janela de relatório de eventos, até dois dias após a exibição inicial dos anúncios em um app.

Considere o caso em que um usuário faz o seguinte:

O usuário recebe um anúncio. A adtech registra uma fonte de atribuição com a API, com uma prioridade 0 (visualização 1).
O usuário recebe um anúncio, registrado com uma prioridade 0 (visualização 2).
O usuário clica em um anúncio, registrado com uma prioridade 1 (clique 1).
O usuário faz uma conversão (acessa a página de destino) em um app do anunciante. A adtech registra um acionador com a API, com prioridade 0 (conversão 1).
- À medida que os acionadores são registrados, a API realiza a atribuição antes de gerar relatórios.
- Há três fontes de atribuição disponíveis: visualização 1, visualização 2 e clique 1. A API atribui o acionador ao clique 1 por ter a prioridade mais alta e ser o mais recente.
- As visualizações 1 e 2 são descartadas e não estão mais qualificadas para atribuição futura.
O usuário adiciona um item ao carrinho no app do anunciante, registrado com uma prioridade de 1 (conversão 2).
- O clique 1 é a única fonte de atribuição qualificada. A API atribui esse acionador ao clique 1.
O usuário adiciona um item ao carrinho no app do anunciante, registrado com uma prioridade de 1 (conversão 3).
- O clique 1 é a única fonte de atribuição qualificada. A API atribui esse acionador ao clique 1.
O usuário adiciona um item ao carrinho no app do anunciante, registrado com uma prioridade de 1 (conversão 4).
- O clique 1 é a única fonte de atribuição qualificada. A API atribui esse acionador ao clique 1.
O usuário realiza uma compra no app do anunciante, registrado com uma prioridade de 2 (conversão 5).
- O clique 1 é a única fonte de atribuição qualificada. A API atribui esse acionador ao clique 1.

Os relatórios de eventos têm as características abaixo:

Por padrão, os três primeiros acionadores atribuídos a um clique e o primeiro acionador atribuído a uma visualização são enviados depois das janelas de relatórios aplicáveis.
Na janela de relatórios, se há acionadores registrados com maior prioridade, eles têm precedência e substituem o acionador mais recente.
No exemplo anterior, as adtechs recebem três relatórios de eventos depois do período de dois dias, relacionados às conversões 2, 3 e 5.
- Todos os cinco acionadores são atribuídos ao clique 1. Por padrão, a API enviaria relatórios para os três primeiros acionadores: conversão 1, conversão 2 e conversão 3.
- No entanto, a prioridade da conversão 4 (1) é maior do que a prioridade da conversão 1 (0). O relatório de eventos da conversão 4 substitui o relatório da conversão 1 que seria enviado.
- Além disso, a prioridade da conversão 5 (2) é maior do que qualquer outro acionador. O relatório de eventos da conversão 5 substitui o relatório da conversão 4 que seria enviado.

Os relatórios agregáveis têm as seguintes características:

Os relatórios agregáveis criptografados são enviados às adtechs assim que são processados, algumas horas após o registro dos acionadores.

Como uma adtech, crie os lotes de acordo com as informações não criptografadas dos relatórios agregáveis. Essas informações ficam no campo shared_info do relatório agregável e incluem um carimbo de data/hora e a origem do relatório. Não é possível criar lotes com base em informações criptografadas nos seus pares de chave-valor de agregação. Como estratégia simples, você pode gerar relatórios em lotes diários ou semanais. O ideal é que os lotes tenham pelo menos 100 relatórios cada.
Cabe às adtechs definir quando e como gerar os lotes de relatórios agregáveis e fazer o envio ao serviço de agregação.
Em comparação com os relatórios de eventos, os relatórios agregáveis podem atribuir mais acionadores a uma fonte.
No exemplo anterior, cinco relatórios agregáveis são enviados, um para cada acionador registrado.

Relatórios de depuração transicionais

A API Attribution Reporting é uma maneira nova e bastante complexa de fazer medições de atribuição sem identificadores entre apps. Dessa forma, oferecemos suporte a um mecanismo de transição para saber mais sobre os Relatórios de atribuição quando o ID de publicidade está disponível, ou seja, quando o usuário não desativou a personalização usando o ID de publicidade e o editor ou o app do anunciante declarou permissões desse ID. Isso garante que a API possa ser totalmente compreendida durante o lançamento, ajuda a eliminar bugs e facilita a comparação do desempenho com alternativas baseadas em IDs de publicidade. Há dois tipos de relatórios de depuração: atribuição concluída e detalhado.

Leia o guia sobre relatórios de depuração transicionais para saber detalhes sobre esses relatórios com medições de app para a Web e da Web para um app.

Relatórios de depuração de atribuição concluída

Os registros de acionador e de origem aceitam um novo campo debug_key de 64 bits (formatado como uma string), que a adtech preenche. source_debug_key e trigger_debug_key são transmitidos sem mudanças nos relatórios de evento e agregados.

Se um relatório for criado com chaves de depuração de fonte e acionador, um relatório de depuração duplicado será enviado com atraso limitado a um endpoint .well-known/attribution-reporting/debug/report-event-attribution. Os relatórios de depuração são idênticos aos normais, incluindo os dois campos de chave de depuração. A inclusão dessas chaves em ambos permite vincular relatórios normais ao fluxo separado de relatórios de depuração.

Para relatórios de eventos:
- Relatórios de depuração duplicados são enviados com atraso limitado. Eles não são suprimidos pelos limites de acionadores disponíveis, o que permite que a adtech entenda o impacto desses limites nos relatórios de eventos.
- Relatórios associados a eventos de acionamento falsos não terão trigger_debug_keys. Isso permite que a adtech entenda melhor como o ruído é aplicado na API.
Para relatórios agregáveis:
- Vamos oferecer suporte a um novo campo debug_cleartext_payload que contém o payload descriptografado somente se source_debug_key e trigger_debug_key estiverem definidos.

Relatórios de depuração detalhados

Os relatórios de depuração detalhados permitem que os desenvolvedores monitorem determinadas falhas nos registros do acionador ou da fonte de atribuição. Esses relatórios são enviados com atraso limitado após os registros do acionador ou da fonte de atribuição para um .endpoint well-known/attribution-reporting/debug/verbose.

Cada relatório detalhado contém os campos abaixo:

Tipo: o que causou a geração do relatório. Confira a lista completa de tipos de relatórios detalhados (link em inglês).
- Em geral, há relatórios detalhados da fonte e do acionador.
- Os relatórios detalhados da fonte exigem que o ID de publicidade esteja disponível para o app do editor. Já os relatórios detalhados do acionador exigem que esse ID esteja disponível para o app do anunciante.
- Os relatórios detalhados do acionador (exceto trigger-no-matching-source) podem incluir a source_debug_key, mas isso só vai ocorrer se o ID de publicidade também estiver disponível para o app do editor.
Corpo: o corpo do relatório, dependendo do tipo.

As adtechs precisam ativar o recebimento de relatórios de depuração detalhados usando um novo campo de dicionário debug_reporting nos cabeçalhos Attribution-Reporting-Register_Source e Attribution-Reporting-Register-Trigger.

Os relatórios detalhados da fonte exigem a ativação apenas do cabeçalho de registro da fonte.
Os relatórios de depuração do acionador exigem a ativação apenas do cabeçalho de registro de acionadores.

Como usar os relatórios de depuração

Se uma conversão tiver ocorrido de acordo com o sistema de medição existente e um relatório de depuração tiver sido recebido para essa conversão, isso significa que o acionador foi registrado.

Para cada Relatório de atribuição de depuração, verifique se você está recebendo um relatório de atribuição normal que corresponde às duas chaves de depuração.

Quando não há correspondência, isso pode ocorrer por vários motivos.

Funciona conforme o esperado:

Comportamentos da API de preservação de privacidade:
- Um usuário atinge a limitação de taxa do relatório, fazendo com que todos os relatórios subsequentes não sejam enviados no período ou uma fonte seja removida devido ao limite de destino pendente.
- Para relatórios de evento: o relatório está sujeito a resposta aleatória (ruído) e é suprimido, ou você pode receber um relatório aleatório.
- Para relatórios de evento: o limite de três relatórios (para cliques) ou um (para visualizações) foi atingido. Os relatórios subsequentes não têm prioridade explícita definida ou têm uma prioridade menor do que os relatórios existentes.
- Os limites de contribuição para relatórios agregáveis foram excedidos.
Lógica de negócios definida pela adtech:
- Um acionador é filtrado por filtros ou regras de prioridade.
Atrasos ou interações de tempo com a disponibilidade da rede, por exemplo, o usuário desativa o dispositivo por um longo período.

Causas não intencionais:

Problemas de implementação:
- O cabeçalho de fonte está configurado incorretamente.
- O cabeçalho do acionador está configurado incorretamente.
- Outros problemas de configuração.
Problemas no dispositivo ou na rede:
- Falhas devido às condições da rede.
- A resposta do registro da fonte ou do acionador não chega ao cliente.
- Bug de API.

Considerações futuras e perguntas em aberto

A API Attribution Reporting está em fase de desenvolvimento. Também estamos explorando outros possíveis recursos para implementação futura, como modelos de atribuição que não são de último clique e casos de uso de medição entre dispositivos.

Além disso, gostaríamos de receber feedback da comunidade relacionado a algumas questões:

Há casos de uso em que você gostaria que a API enviasse relatórios sobre a instalação verificada? Esses relatórios seriam contabilizados na respectiva limitação de taxa das adtechs.
Você prevê alguma dificuldade para transmitir o InputEvent do app à adtech para o registro da fonte?
Você tem casos de uso de atribuição especiais para apps pré-carregados ou reinstalados?