API Attribution Reporting: guia de integração

Ao ler a documentação do Sandbox de privacidade do Android, use o botão Prévia para desenvolvedores ou Beta para selecionar a versão do programa com que você está trabalhando, porque as instruções podem variar.

A API Attribution Reporting foi projetada para oferecer suporte aos principais casos de uso de medição de conversões e atribuição em apps e na Web sem depender de identificadores do usuário entre partes diferentes. Em comparação com designs comuns atuais, os implementadores da API Attribution Reporting precisam fazer algumas considerações importantes de alto nível:

  • Os relatórios de evento incluem dados de conversão de baixa fidelidade. Um pequeno número de valores de conversão funciona bem.
  • Os relatórios agregáveis incluem dados de conversão de maior fidelidade. Suas soluções precisam criar chaves de agregação com base nos seus requisitos comerciais e no limite de 128 bits.
  • Os modelos de dados e o processamento da solução precisam considerar os limites de taxa para os acionadores disponíveis, os atrasos no envio de eventos do acionador e o ruído aplicado pela API.

Para o planejamento de integração, este guia fornece uma visão abrangente, que pode incluir recursos ainda não implementados no estágio atual do Sandbox de privacidade na prévia para desenvolvedores Android. Nesses casos, são fornecidas orientações sobre o cronograma.

Nesta página, usamos origem para representar um clique ou uma visualização e acionador para representar uma conversão.

O gráfico abaixo mostra as diferentes opções de fluxo de trabalho para integração de atribuições. Seções listadas na mesma coluna (circuladas em verde) podem ser trabalhadas em paralelo. Por exemplo, o engajamento do parceiro pode ser feito ao mesmo tempo que a atribuição no nível do evento entre apps.

Diagrama do fluxo de trabalho de integração de atribuição

Figura 1. Fluxo de trabalho de integração de atribuição.

Pré-requisitos e configuração

Conclua as etapas nesta seção para entender melhor a API Attribution Reporting. As etapas vão preparar você para coletar resultados significativos ao usar a API no ecossistema de adtech.

Conhecer a API

  1. Leia a proposta de design para se familiarizar com a API Attribution Reporting e os recursos dela.
  2. Leia o guia para desenvolvedores para saber como incorporar o código e as chamadas de API que você precisará para seus casos de uso.
  3. Envie feedback sobre a documentação, principalmente sobre as perguntas abertas.
  4. Inscreva-se para receber atualizações sobre a API Attribution Reporting. Assim, você vai ficar por dentro dos novos recursos introduzidos em versões futuras.

Configurar e testar o app de exemplo

  1. Quando estiver tudo pronto para iniciar a integração, prepare-se com a prévia para desenvolvedores mais recente no Android Studio.
  2. Configure endpoints simulados de servidores para inscrições em eventos e envio de relatórios. Temos modelos simulados que podem ser usados junto com as ferramentas disponíveis on-line.
  3. Faça o download e execute o código no nosso app de exemplo para se familiarizar com o registro de origens e acionadores.
    1. Defina as janelas de tempo de envio dos relatórios. A API oferece suporte a janelas de 2 dias, 7 dias ou um período personalizado entre 2 e 30 dias.
    2. Depois de registrar origens e acionadores executando e usando o app de exemplo e após o período de tempo definido, verifique se você recebeu um relatório em nível de evento e um relatório agregável criptografado. Se você precisar depurar relatórios, eles podem ser gerados mais rapidamente forçando a execução dos jobs de relatório.
    3. Analise os resultados da atribuição de app para app. Confirme se os dados nesses resultados são os esperados para os casos de último toque e pós-instalação.

  4. Depois de entender como a API do cliente e o servidor funcionam juntos, use o app de exemplo para orientar sua própria integração. Configure seu próprio servidor de produção e adicione chamadas de registro de eventos aos seus apps.

Pré-integração

Registre sua organização no Sandbox de privacidade do Android. Esse registro foi criado para evitar a duplicação desnecessária de plataformas de adtech, o que permitiria o acesso a mais informações do que o necessário sobre as atividades do usuário.

Engajamento de parceiros

Os parceiros de adtech (MMP/SSP/DSP) geralmente criam soluções de atribuição integrada. Com as etapas desta seção, você pode se preparar para ter sucesso ao interagir com seus parceiros de adtech.

  1. Agende uma conversa com seus principais parceiros de medição para discutir o teste e a adoção da API Attribution Reporting. Os parceiros de medição podem incluir redes de adtech, SSPs, DSPs, anunciantes ou qualquer outro parceiro com quem você queira trabalhar no momento.
  2. Colabore com seus parceiros de medição para definir os cronogramas de integração, desde o teste inicial até a adoção.
  3. Esclareça com seus parceiros de medição quais áreas cada um de vocês vai abordar no design de atribuição.
  4. Estabeleça canais de comunicação entre os parceiros de medição para sincronizar os cronogramas e os testes de ponta a ponta.
  5. Crie fluxos de dados de alto nível em parceiros de medição. As principais considerações incluem:
    • Como os parceiros de medição vão registrar origens de atribuição com a API Attribution Reporting?
    • Como as redes de adtech vão registrar acionadores com a API Attribution Reporting?
    • Como cada adtech vai validar as solicitações de API e retornar respostas para concluir os registros de origem e acionador?
    • Existe algum relatório que precise ser compartilhado entre os parceiros fora da API Attribution Reporting?
    • Há outros pontos de integração ou alinhamento necessários entre os parceiros? Por exemplo, você e seus parceiros precisam trabalhar na eliminação de duplicação de conversões ou alinhar as chaves de agregação?
  6. Se a atribuição de app para Web for aplicável, agende uma discussão com os parceiros de medição na Web para discutir o design, o teste e a adoção da API Attribution Reporting. Consulte as perguntas da etapa anterior ao iniciar conversas com parceiros da Web.

Criar protótipos da atribuição no nível do evento de cada aplicativo

Nesta seção, você vai configurar uma atribuição básica de app a app com relatórios em nível de evento no seu app ou SDK. É necessário concluir esta seção para começar a prototipar a atribuição do servidor de agregação.

  1. Configure um servidor de coleta para registros de eventos. É possível fazer isso usando a especificação fornecida para gerar um servidor simulado ou configurar o seu próprio com o código de servidor de exemplo (links em inglês).
  2. Adicione chamadas de evento de origem de registro ao seu SDK ou app quando os anúncios forem exibidos.
    • Confira algumas considerações importantes:
      • Verifique se os códigos de evento de origem estão disponíveis e são transmitidos corretamente para as chamadas da API de registro de origem.
      • Também é possível transmitir um "InputEvent" para registrar origens de cliques.
      • Determine como você vai configurar a prioridade da origem para diferentes tipos de eventos. Por exemplo, atribua uma prioridade alta a eventos considerados de alto valor, como cliques em vez de visualizações.
      • O valor padrão de expiração é permitido para testes. Como alternativa, diferentes janelas de expiração podem ser configuradas.
      • Os filtros e as janelas de atribuição podem ser deixados como padrões para testes.
    • As considerações opcionais incluem:
      • Crie chaves de agregação, se você quiser trabalhar com elas.
      • Considere sua estratégia de redirecionamento ao estabelecer como quer trabalhar com outros parceiros de medição.
  3. Adicione registro de eventos de acionador ao SDK ou app para registrar eventos de conversão.
    • Confira algumas considerações importantes:
    • As considerações opcionais incluem as seguintes:
      • Puar a criação de chaves de eliminação de duplicação até que faça testes de acurácia.
      • Não criar chaves e valores de agregação até que o suporte ao teste de simulação esteja disponível.
      • Pular redirecionamentos até estabelecer como quer trabalhar com outros parceiros de medição.
      • A prioridade do acionador não é essencial para testes.
      • É provável que os filtros possam ser ignorados para testes iniciais.
  4. Teste se os eventos de origem estão sendo gerados para os anúncios e se os acionadores estão gerando a criação de relatórios de eventos.

Testes de simulação

Esta seção mostra como testar o impacto da mudança provável das conversões atuais em eventos e relatórios agregáveis nos sistemas de relatórios e otimização. Isso vai permitir que você inicie o teste de impacto antes de concluir a integração.

Para testar, é necessário simular a geração de eventos e os relatórios agregáveis com base nos registros históricos de conversão, além de receber os resultados agregados de um servidor de agregação simulado. Esses resultados podem ser comparados aos números históricos de conversão para ver como a precisão dos relatórios mudaria.

Os modelos de otimização, como os cálculos de taxa de conversão estimada, podem ser treinados nesses relatórios para comparar a precisão desses modelos com os criados com os dados atuais. Também é uma chance de testar diferentes estruturas de chaves de agregação e o impacto delas nos resultados.

  1. Configure a biblioteca de simulação de medição em uma máquina local.
  2. Leia a spec (em inglês) sobre como os dados de conversão precisam ser formatados para serem compatíveis com o gerador de relatórios simulado.
  3. Crie suas chaves de agregação com base nos requisitos comerciais.
    • Confira algumas considerações importantes:
      • Considere as dimensões críticas que seus clientes ou parceiros precisam agregar e concentre sua avaliação nelas.
      • Determine o número mínimo de dimensões agregadas e cardinalidades necessárias para seus requisitos.
      • As principais partes do acionador e da origem não podem exceder 128 bits.
      • Se as soluções envolverem a contribuição de vários valores por evento de acionador, dimensione os valores de acordo com o orçamento de contribuição máxima, L1. Isso vai ajudar a minimizar o impacto de ruídos.
      • Veja um exemplo que detalha a definição de uma chave para coletar contagens de conversões agregadas em nível de campanha e uma chave para coletar valores de compra agregados em nível geográfico.
  4. Execute o gerador de relatórios para criar relatórios agregáveis e de eventos.
  5. Gere os relatórios agregáveis com os servidores de agregação simulados para receber relatórios resumidos.
  6. Faça experimentos de utilitários:
    • Compare os totais de conversão dos relatórios de eventos e de resumo com os dados históricos de conversão para determinar a precisão do relatório de conversões. Para melhores resultados, execute os testes e as comparações de relatórios em uma parte ampla e representativa da base de anunciantes.
    • Treine seus modelos novamente com base nos dados de relatórios de eventos e possivelmente nos dados de relatórios de resumo. Compare a precisão com modelos criados com base em dados históricos de treinamento.
    • Teste diferentes estratégias de agrupamento e verifique como elas afetam seus resultados.
      • Confira algumas considerações importantes:
      • Pontualidade dos relatórios de resumo para ajuste de lances.
      • Frequências médias de eventos atribuíveis no dispositivo. Por exemplo, usuários antigos que voltam com base nos dados históricos de eventos de compra.
      • Nível de ruído. Quanto mais lotes, menor é a agregação e isso significa mais ruído.

Atribuição do servidor de agregação de protótipos: configuração

Estas etapas vão garantir que você receba relatórios agregáveis dos seus eventos de origem e acionador.

  1. Configure o servidor de agregação:
  2. Crie suas chaves de agregação com base nos requisitos comerciais. Se você já concluiu essa tarefa na seção no nível do evento de app para app, pule essa etapa.
  3. Configure um servidor de coleta para relatórios agregáveis. Se você já criou um na seção no nível do evento de app para app, vai poder reutilizá-lo.

Atribuição do servidor de agregação de protótipos: integração

Para continuar, conclua a seção Atribuição do servidor de agregação de protótipos: configuração ou App de protótipo para atribuição no nível do evento do app.

  1. Adicione dados da chave de agregação aos eventos de origem e acionador. Isso provavelmente vai exigir a transmissão de mais dados sobre o evento do anúncio, como o ID da campanha, ao SDK ou app para incluir na chave de agregação.
  2. Colete relatórios agregáveis de app para app dos eventos de origem e do acionador registrados com dados da chave de agregação.
  3. Teste diferentes estratégias de loteamento ao gerar esses relatórios agregáveis usando o servidor de agregação e observe como elas afetam os resultados.

Iterar o design com recursos opcionais

Veja a seguir os recursos adicionais que você pode incluir na sua solução de métricas.

  1. A definição de uma chave de depuração possibilita que você receba um relatório inalterado de um evento de origem ou de acionador com os relatórios gerados pela API Attribution Reporting. É possível usar chaves de depuração para comparar relatórios e encontrar bugs durante a integração.

Personalizar comportamentos de atribuição

  1. Atribuição para acionadores pós-instalação
    • Esse recurso pode ser usado quando os acionadores pós-instalação precisarem ser atribuídos à mesma origem que gerou a instalação, mesmo que haja outras origens qualificadas que ocorreram mais recentemente.
    • Por exemplo, pode haver um caso em que um usuário clica em um anúncio que gera uma instalação. Após a instalação, o usuário clica em outro anúncio e faz uma compra. Nesse caso, a empresa de adtech pode querer que a compra seja atribuída ao primeiro clique, em vez do clique de reengajamento.
  2. Use filtros para ajustar os dados nos relatórios de eventos
    • É possível definir que os filtros de conversão ignorem os acionadores selecionados e os excluam dos relatórios de eventos. Como há limites para o número de acionadores por origem de atribuição, os filtros permitem que você inclua somente os acionadores que fornecem as informações mais úteis nos seus relatórios de eventos.
    • Os filtros também podem ser usados para filtrar seletivamente alguns acionadores, ignorando todos eles. Por exemplo, se você tiver uma campanha segmentada para instalações de apps, convém filtrar os acionadores pós-instalação a serem atribuídos a origens dessa campanha.
    • Os filtros também podem ser usados para personalizar os dados do acionador com base nos dados de origem. Por exemplo, uma origem pode especificar "product" : ["1234"], em que product é a chave de filtro e 1234 é o valor. Qualquer acionador com uma chave de filtro de "product" que tenha um valor diferente de "1234" será ignorado.
  3. Prioridade personalizada do acionador e da origem
    • Se várias origens de atribuição puderem ser associadas a um acionador ou se vários acionadores puderem ser atribuídos a uma origem, será possível usar um número inteiro assinado de 64 bits para priorizar determinadas atribuições de origem/acionador em vez de outras.

Como trabalhar com MMPs e outros

  1. Redireciona a terceiros para eventos de origem e acionador
    • É possível definir URLs de redirecionamento para permitir que várias plataformas de adtech registrem uma solicitação. Isso pode ser usado para ativar a eliminação de duplicação em várias redes na atribuição.
  2. Chaves de eliminação de duplicação
    • Quando um anunciante usa várias plataformas de adtech para registrar o mesmo evento acionador, uma chave de eliminação de duplicação pode ser usada para diferenciar esses relatórios repetidos. Se nenhuma chave de eliminação de duplicação é informada, é possível que acionadores duplicados sejam informados como eventos únicos para as plataformas.

Como trabalhar com a medição em várias plataformas

  1. Atribuição cruzada entre apps e Web (disponível no final do quarto trimestre)
    • Oferece suporte a casos de uso em que um usuário vê um anúncio em um app e faz uma conversão em um navegador para dispositivos móveis ou em um app, ou vice-versa.