Conheça a prévia para desenvolvedores do Sandbox de privacidade do Android. Veja como começar e envie feedback.

Como gerar relatórios de atribuição

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Enviar feedback

Atualmente, é comum que as soluções de atribuição e de métricas de dispositivos móveis usem identificadores entre partes diferentes, como 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, e para oferecer suporte aos principais casos de uso para avaliação de métricas de conversão e atribuição em apps e na Web.

Essa API inclui os mecanismos estruturais abaixo que oferecem um framework para melhor a privacidade. Eles serão apresentados em mais detalhes nas próximas seções deste documento:

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, ou seja, os 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:

  1. A adtech realiza um processo de registro para usar a API Attribution Reporting.
  2. A adtech registra fontes de atribuição, que são cliques ou visualizações de anúncios, com a API Attribution Reporting.
  3. A adtech registra acionadores, que são conversões de usuários no app ou no site do anunciante, usando a API Attribution Reporting.
  4. A API Attribution Reporting combina acionadores e 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 agregáveis, que são enviados do dispositivo para adtechs.

Registrar uma adtech

Para acessar a API Attribution Reporting e garantir que os mecanismos de privacidade funcionem conforme o esperado, todas as plataformas de adtech, incluindo a do Google, precisam passar por um processo de registro simples. Os detalhes desse processo ainda estão em desenvolvimento e seu feedback é muito útil.

O processo de registro garante que as plataformas de adtech não se dupliquem desnecessariamente para ter acesso a mais informações sobre as atividades de um usuário em apps ou sites. Por exemplo, a API Attribution Reporting limita a quantidade de rastreamento e informações que uma plataforma de adtech consegue visualizar de um determinado acionador e fonte de atribuição. Mais detalhes sobre esses limites são apresentados abaixo, na seção sobre como acessar dados de medição em relatórios de atribuição.

As empresas podem se registrar várias vezes, desde que haja uma necessidade comercial legítima, como a operação de várias linhas de produtos independentes, e que a empresa não combine dados de vários registros para contornar as restrições de privacidade.

Durante o registro, as plataformas de adtech fornecem informações como as abaixo:

  • Informações comerciais e de contato
  • URLs usados para registrar fontes de atribuição e acionadores
  • URLs de postback usados para receber relatórios de evento e agregáveis
  • Casos de uso da API Attribution Reporting

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, para um evento de clique, ou null, para um de visualização.

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 os campos abaixo:

  • ID do evento da fonte: uma DOMString que codifica um número inteiro de 64 bits sem assinatura. Esse valor representa os dados de evento associados a essa fonte de atribuição (clique ou visualização do anúncio).
  • 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, mas o período pode variar entre 2 e 30 dias. Esse número é arredondado para o dia mais próximo.
  • Prioridade de fonte (opcional): um número inteiro de 64 bits, assinado, usado para selecionar a fonte de atribuição a que um determinado acionador vai ser associado caso ele tenha várias opções.

    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 plataforma de 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.

    Quanto maior o valor, maior a prioridade.

  • Janelas de atribuição de instalação e pós-instalação (opcional): usadas para determinar a atribuição para eventos pós-instalação, descritos mais adiante neste documento.

  • 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:

  1. O SDK de adtechs 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);
    
  2. 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
    
  3. 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-Redirects: https://adtechpartner1.example?their_ad_click_id=567,
    https://adtechpartner2.example?their_ad_click_id=890
    
  4. A API faz uma solicitação para cada URL especificado em Attribution-Reporting-Redirects. Neste exemplo, dois URLs de parceiros de adtech são especificados, 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.

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

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

Registrar um acionador (conversão)

As plataformas de adtech 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 de adtechs precisa incluir um cabeçalho HTTP com o nome Attribution-Reporting-Register-Event-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 campos abaixo:

  • Dados do acionador: dados para identificar o evento acionador (três bits para cliques, um bit para visualizações).
  • Prioridade do acionador (opcional): um número inteiro assinado de 64 bits que representa a prioridade do acionador em comparação a outros acionadores da mesma fonte de atribuição. 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): número inteiro de 64 bits assinado, que é usado para identificar casos em que um acionador é registrado várias vezes por uma única plataforma de adtech para a mesma fonte de atribuição.
  • 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.
  • Filtragem de relatórios de atribuição (opcional): usada para filtrar seletivamente acionadores ou dados de acionadores. Para mais detalhes, consulte a seção Filtros de acionador nesta página.

Opcionalmente, 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, assim várias adtechs conseguem registrar uma solicitação.

Diversas adtechs podem registrar o mesmo evento acionador usando redirecionamentos no campo Attribution-Reporting-Redirects ou várias chamadas para o método registerTrigger(). Recomendamos que você use 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:

  1. O SDK de adtechs chama a API para iniciar o registro de acionador com um URI usado no registro:

    registerTrigger(
        Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
    
  2. A API faz uma solicitação para https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

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

    Attribution-Reporting-Register-Event-Trigger: {
        "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-Redirects: https://adtechpartner.example?app_install=567
    
  4. A API faz uma solicitação para cada URL especificado em Attribution-Reporting-Redirects. Neste exemplo, somente um URL é especificado, de modo que a API faz uma solicitação para https://adtechpartner.example?app_install=567.

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

    Attribution-Reporting-Register-Event-Trigger: {
        "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 adtechs registram uma fonte de atribuição, conforme descrito mais adiante neste documento, essa atribuição ocorre de maneira independente para cada uma delas. A fonte de atribuição com maior prioridade é atribuída com o evento acionador. Caso haja várias fontes de atribuição com a mesma prioridade, a API vai escolher 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 seletivamente os acionadores, 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.

As adtechs também podem escolher os dados do acionador com base nos dados de evento da fonte. Por exemplo, o 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 pós-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 2 a 7 dias, com um intervalo aceito de 2 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.

    Estamos procurando maneiras de oferecer suporte a casos de uso em que o usuário desinstala e reinstala o app.

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 pós-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 o primeiro acesso, mas pode ser qualquer tipo de acionador.
Ele é atribuído ao clique 1 e 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.
Ele é atribuído ao clique 1 e 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 adtechs podem registrar qualquer tipo de acionador. Em outras palavras, o primeiro acionador não precisa ser o 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 vai 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 de relatórios.

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 vê 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, como 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 de apps e da 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 neste documento.

Existem limites para quantos acionadores podem ser atribuídos a uma única fonte. Para mais detalhes, leia a seção sobre como conferir dados de medição em relatórios de atribuição mais adiante neste documento. 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 "comprar" em vez de "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. Portanto, 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 que a adtech registrou com a API.

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():

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

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

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-Redirects 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, o app do anunciante 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 que ele esteja usando 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-Redirects.

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 acionador 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-Redirects, 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 em várias redes

No exemplo descrito nesta seção, o anunciante usa duas plataformas de adtech para 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 concluir a inscrição para usar a API Attribution Reporting.

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

Como a Adtech A, a Adtech B também incluiu o URI do MMP no cabeçalho Attribution-Reporting-Redirects. 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 visualiza 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-Redirects. 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.

A Figura 1 ilustra o processo descrito na lista anterior:

Figura 1. 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

Embora recomendemos o uso de redirecionamentos para permitir que várias adtechs registrem fontes de atribuição e acionadores, reconhecemos que pode haver cenários em que o uso de redirecionamentos 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

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

Registro de origem

No registro de origem, a rede de adtech de veiculação pode escolher compartilhar as chaves de agregação de origem ou um subconjunto delas em vez de redirecionar. A adtech de veiculação não precisa usar essas chaves de origem 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 em que tipos de chaves 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 de acionadores, a adtech de medição escolhe quais partes da chave do lado da fonte serão aplicadas a cada uma, incluindo conteúdo compartilhado por adtechs veiculadas.

Além disso, a adtech de medição também precisa especificar a lógica de atribuição de hierarquia por 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 (por exemplo, fontes que não usavam um redirecionamento).

Atribuição

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

  • O usuário clicou nos anúncios veiculados pelas adtechs A, B, C e D. Em seguida, o usuário instalou o app do anunciante, que usa um parceiro de tecnologia de anúncios de medição (MMP, na sigla em inglês).

  • A Adtech A redireciona as origens dela para o MMP.

  • A Adtech B e a 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 origem 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 origem no redirecionamento dessa adtech.

  • A Adtech B, já que a Adtech B 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.

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 neste documento:

  • Os relatórios de nível de evento associam uma fonte de atribuição específica (clique ou visualização) a bits limitados de dados de 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 a nível 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 ele possa ser enviado ao URL de postback de cada adtech durante uma das janelas de tempo para envio de relatórios descritas em mais detalhes posteriormente neste documento.

Os relatórios a nível de evento são úteis quando poucas informações são necessárias sobre o acionador. 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 a nível 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 a nível de evento.

O relatório a nível 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

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 é de:

  • 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}.
  • 10 adtechs podem registrar uma única fonte de atribuição ou acionador (por Attribution-Reporting-Redirects)

Esses limites são aplicados depois que as prioridades relacionadas às fontes de atribuição e aos acionadores são consideradas.

Desaceleramento e limitações de taxa

Para limitar a quantidade de vazamentos de identidade do usuário entre um par (origem, destino), a API limita a quantidade total de informações enviadas por um usuário em um 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 distintos com fontes não expiradas por app de origem.

Mecanismos de preservação de privacidade aplicados a relatórios a nível de evento

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 a nível de evento.

Framework para ruídos de privacidade diferencial

Um dos objetivos dessa API é permitir que as métricas em nível 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 fonte.

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 origens de navegação.
  • p=0,00025% para origens 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:

  • De um a dois acionadores para fontes de atribuição de visualização de anúncios
  • Três acionadores para fontes de atribuição de cliques em anúncios

Esses limites são aplicados depois que as prioridades relacionadas às fontes de atribuição e aos acionadores são consideradas.

Janelas de tempo específicas para enviar relatórios

Os relatórios sobre fontes de atribuição de visualização de anúncios são enviados uma hora após o vencimento da fonte. A validade pode ser configurada, mas não pode ser menor que dois dias nem maior que 30 dias.

Os relatórios sobre fontes de atribuição de cliques em anúncios não podem ser configurados e são enviados antes do fim da validade, 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 programado. 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 dois dias nem maior que 30 dias.

Relatórios agregáveis

Relatórios agregáveis fornecem dados dos acionadores de maior fidelidade do dispositivo com mais rapidez, como complemento aos dados oferecidos pelos relatórios a nível 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, apresentado na Figura 2, é este:

  1. O dispositivo envia relatórios agregáveis criptografados para a adtech. Em um ambiente de produção, a adtech não pode usar esses relatórios diretamente.
  2. A adtech envia um lote de relatórios agregáveis para o serviço de agregação.
  3. O serviço de agregação lê um lote de relatórios agregáveis e, em seguida, descriptografa e agrega esses relatórios.
  4. Os dados agregados finais são enviados de volta à adtech em um relatório resumido {: .external} (link em inglês).
Figura 2. 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 auxiliam na proteção 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 neste documento:

  • O serviço de agregação é o único que a adtech precisa implantar.
  • Os serviços de gerenciamento de chaves e orçamento de privacidade são executados por partes confiáveis, chamadas de verificadores. Esses verificadores atestam que o código que executa o serviço de agregação é o código disponibilizado publicamente pelo Google e que todos os usuários do serviço de agregação usam os mesmos serviços de gerenciamento de chaves e orçamento de privacidade.
Serviço de agregação

As plataformas de adtech precisam implantar, antecipadamente, um serviço de agregação com base em 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 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 o documento do serviço de agregação (link em inglês) 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.

Serviço de orçamento de privacidade

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. É permitido executar uma descriptografia por acionador.

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 de relatórios a nível 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 ao URI da fonte de atribuição, a adtech pode registrar uma lista de chaves de agregação, com o nome histogram_contributions, ao responder com um novo cabeçalho HTTP Attribution-Reporting-Register-Aggregate-Source, incluindo os campos abaixo para cada chave de agregação da lista:

  • ID do evento da fonte: uma string com o nome da chave. Usado como chave de junção para combinar as chaves do lado do acionador e formar a chave final.
  • Parte da chave: um valor de bitstring da 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 em nível de campanha
  • valores de compra agregados em nível de área geográfica.
// This is where the Attribution-Reporting-Register-Source object appears when
// an adtech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Aggregatable-Source:
[{
// Generates a "0x159" key piece named (low order bits of the key) for the key
// named "campaignCounts".
  "id": "campaignCounts",
// User saw an ad from campaign 345 (out of 511).
  "key_piece": "0x159",
},
{
// Generates a "0x5" key piece (low order bits of the key) for the key named "geoValue"
  "id": "geoValue",
// Source-side geo region = 5 (US), out of a possible ~100 regions.
  "key_piece": "0x5",
}]

Registrar o acionador agregável

O registro de acionadores inclui outros dois cabeçalhos.

O primeiro cabeçalho é usado para registrar uma lista de chaves agregadas no lado do acionador. A adtech precisa responder com o cabeçalho HTTP Attribution-Reporting-Register-Aggregatable-Trigger-Data, incluindo os campos a seguir 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 cabeçalho é usado para registrar uma lista de valores que precisam contribuir com cada chave. A adtech precisa responder com o cabeçalho HTTP Attribution-Reporting-Register-Aggregatable-Values.

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

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-Event-Trigger object appears
// when an adtech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-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.
Attribution-Reporting-Register-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}{ε}) \]

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 acionadores e de fontes de atribuição 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:

  1. O usuário vê um anúncio. As adtechs registram uma fonte de atribuição com a API, com uma prioridade 0 (visualização 1).
  2. O usuário vê um anúncio, registrado com uma prioridade 0 (visualização 2).
  3. O usuário clica em um anúncio, registrado com uma prioridade 1 (clique 1).
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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 houver acionadores registrados com maior prioridade, eles vão ter precedência e substituir o acionador mais recente.
  • No exemplo anterior, as adtechs recebem três relatórios de eventos depois da janela de dois dias para as 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 vai ser enviado.

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

  • 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, você cria os lotes com base nas informações que não são criptografadas nos relatórios agregáveis. Essas informações ficam no campo shared_info do relatório agregável e incluem o 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 estendidos

A API Attribution Reporting é uma maneira nova e bastante complexa de fazer medições de atribuição sem identificadores entre apps. Por isso, estamos abertos a incluir um mecanismo de transição para saber mais sobre os Relatórios de atribuição quando o ID de publicidade está disponível. Por exemplo, quando o usuário não aceitou a personalização usando o ID. Isso garante que a API seja totalmente compreendida durante o lançamento, elimine bugs e facilite a comparação do desempenho com alternativas baseadas em ID de publicidade.

Os registros de origem e de acionador aceitam um novo campo debug_key de 64 bits, que a adtech preenche. source_debug_key e trigger_debug_key serão transmitidos sem mudanças nos relatórios agregados e no nível do evento.

Se um relatório for criado com chaves de depuração de origem 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 serã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 a nível de evento:
    • Os relatórios de depuração duplicados são enviados com atraso limitado. Portanto, eles não são suprimidos por limites de acionadores disponíveis, o que permite que a adtech entenda o impacto desses limites no nível do evento relatórios
    • Os 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.
  • Consulte Relatórios de atribuição: medição de vários apps e da Web para consultar mais detalhes sobre relatórios de depuração com a medição de apps para Web e Web para app.

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 origem seja removida devido ao limite de destino pendente.
    • Para relatórios a nível 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 em nível 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 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 origem 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 de origem 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:

  1. Pretendemos permitir que várias adtechs registrem fontes de atribuição e acionadores para liberar a avaliação de métricas por terceiros. Na proposta atual, apenas a plataforma de adtech que originou as chamadas de API pode especificar uma lista de adtechs de terceiros. Para simplificar o design da API, poderíamos permitir que adtechs executassem redirecionamentos em cadeia, especificando apenas a próxima adtech.
  2. Para o registro de fonte de atribuição, estamos avaliando se o design proposto para terceiros e redirecionamentos é viável, inclusive para redes com autoatribuição. Especificamente, queremos saber se você precisa saber todos os elementos no caminho de redirecionamento.
  3. Ao registrar uma fonte de atribuição, as adtechs podem especificar apenas um destino de app. Queremos saber se isso funciona para seus casos de uso.
  4. Ao registrar uma fonte de atribuição, você pode definir um prazo de validade, que é equivalente a uma janela de lookback. A expiração mínima aceita é de dois dias a partir de quando a fonte de atribuição aconteceu. Há casos de uso em que esse fluxo de trabalho falha?
  5. 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.
  6. Você prevê alguma dificuldade para transmitir o InputEvent do app à adtech para o registro de origem?