Atualizações das propostas do Attribution Reporting em janeiro de 2022

A proposta de relatórios de atribuição passou por várias mudanças para atender ao feedback da comunidade, desde mudanças no mecanismo da API até novas funcionalidades.

Para quem é esta postagem?

Esta postagem é para você:

  • Se você já entende a API, por exemplo, se você tem observado ou participado das discussões no repositório do WICG e quer entender o lote de mudanças feitas na proposta em janeiro de 2022.
  • Se você estiver usando a API Attribution Reporting em uma demonstração ou em um experimento em produção.

Se você está começando a usar essa API e/ou ainda não a experimentou, acesse diretamente a introdução à API.

Migração futura

Depois que essas mudanças forem implementadas no Chrome: se você usar relatórios de nível de evento da API Attribution Reporting em uma demonstração ou em um experimento em produção (teste de origem), será necessário editar o código para que a API continue funcionando. Você também pode usar os novos recursos.

Este artigo também lista as mudanças nos relatórios agregáveis. No entanto, essas mudanças, se implementadas, não vão exigir nenhuma ação ou migração, já que ainda não há implementação de navegador para relatórios agregáveis no momento em que este artigo foi escrito.

Alterações de nome

Relatórios de resumo e relatórios agregáveis

O que você pode ter visto descrito como relatórios agregados agora será chamado de relatórios resumidos.

Os relatórios resumidos são a saída final da agregação de vários relatórios agregáveis, antes chamados de contribuições ou contribuições de histograma.

Mudanças no mecanismo da API

Registro de origem com base no cabeçalho (relatórios no nível do evento)

O que vai mudar e por quê?

Quando o usuário visualiza ou clica em um anúncio, o navegador (localmente no dispositivo do usuário) registra esse evento, junto com parâmetros específicos para relatórios de atribuição, como attributionsourceeventid, attributiondestination, attributionexpiry e outros. Os valores desses parâmetros são definidos pela adtech.

A forma como esses parâmetros são definidos está mudando.

Na proposta anterior, os parâmetros precisavam ser incluídos do lado do cliente: nas tags de âncora como atributos HTML ou como argumentos de uma chamada baseada em JS. Os parâmetros precisavam ser conhecidos no momento do clique ou da visualização.

Na nova proposta, o valor desses parâmetros é definido no servidor de adtech.

Diagrama do registro de origem baseado em cabeçalho

Isso tem várias vantagens, principalmente em termos de segurança: o mecanismo de cabeçalho dá à origem do relatório, geralmente uma adtech, controle direto sobre se uma fonte de atribuição está registrada no escopo. Isso mitiga parcialmente as preocupações com fraudes, já que, com essa mudança, um navegador genuíno nunca vai registrar uma fonte sem a ativação da origem do relatório.

Como funciona o registro de origem?

  1. Para um determinado anúncio, a adtech agora precisa definir um atributo específico do lado do cliente attributionsrc. O valor desse atributo é um URL para o qual o navegador vai enviar uma solicitação. Essa solicitação vai incluir um novo cabeçalho HTTP Attribution-Reporting-Source-Info cujo valor, navigation ou event,, especifica se a origem foi um clique ou uma visualização, respectivamente.
  2. Ao receber essa solicitação, o servidor de rastreamento de clique/visualização precisa responder com um cabeçalho HTTP, Attribution-Reporting-Register-Source, que contém os parâmetros de atribuição desejados.

  3. A origem que retorna esse cabeçalho agora é a origem do relatório (anteriormente definida como attributionreportto).

    Cabeçalho de resposta HTTP Attribution-Reporting-Register-Source:

    {
  "source_event_id": "267630968326743374",
  "destination": "https://toasters.example",
  "expiry": "604800000"
}

Saiba mais na explicação técnica

Registrar fontes de atribuição

Participar da discussão pública

Problema 261

Acionador de atribuição baseado em cabeçalho (relatórios de eventos)

O que vai mudar e por quê?

Assim como o registro de clique ou visualização, a nova proposta muda o acionador de atribuição, quando uma adtech instrui o navegador a registrar uma conversão, para uma abordagem baseada em cabeçalho.
Esse mecanismo está alinhado com o registro de origem com base em cabeçalho e é mais convencional do que o mecanismo de redirecionamento usado anteriormente.

Além disso, na nova proposta, o atributo attributionsrc é necessário na página de conversão.

O motivo é uma questão de permissões: na proposta anterior, o site do acionador (geralmente um site do anunciante) tinha controle geral sobre o recurso usando um cabeçalho Permissions-Policy, mas não tinha controle granular no nível do elemento sobre se um elemento pode enviar uma solicitação para uma parte que acionaria uma atribuição. O attributionsrc muda isso: esse marcador obrigatório permite que o anunciante monitore e controle quais elementos podem acionar uma atribuição.

No lado da origem, normalmente um site do editor, há um controle de toda a página usando Permissions-Policy, bem como um controle de todo o elemento usando attributionsrc.

Como funciona o acionador de atribuição?

Ao receber uma solicitação de pixel e decidir que ela precisa ser categorizada como uma conversão, uma adtech precisa responder com um novo cabeçalho HTTP
Attribution-Reporting-Register-Event-Trigger.

O valor desse cabeçalho especifica como tratar o evento de acionamento como um objeto JSON. Essas são as mesmas informações que foram definidas como parâmetros de consulta na proposta anterior.

Cabeçalho de resposta HTTP Attribution-Reporting-Register-Event-Trigger:

    [{
        trigger_data: (unsigned 3-bit integer),
        trigger_priority: (signed 64-bit integer),
        deduplication_key: (signed 64-bit integer)
    }]

Redirecionamento (opcional)

Opcionalmente, o servidor de adtech pode fazer com que a resposta que contém Attribution-Reporting-Register-Event-Trigger seja uma resposta de redirecionamento. Com isso, terceiros podem observar o evento de conversão e instruir o navegador a atribuí-lo.

A redirecionamento é opcional e não é necessária quando uma adtech e um terceiro têm pixels na página.

Confira mais detalhes em Relatórios de terceiros.

Saiba mais na explicação técnica

Atribuição do acionador

Participar da discussão pública

Problema 91

Nenhum worklet (relatórios agregáveis)

O que vai mudar e por quê?

Na proposta anterior de relatórios agregáveis, o acesso ao JavaScript era necessário para invocar um worklet, um mecanismo baseado em JavaScript, que geraria esses relatórios.

Na nova proposta, nenhum worklet é necessário. Em vez disso, uma adtech definiria de forma declarativa (por meio de cabeçalhos HTTP) as regras que o navegador precisa usar para gerar relatórios agregáveis.

A nova proposta oferece vários benefícios:

  • Implementação do navegador:o novo design, ao contrário do design do worklet, é muito mais simples porque não requer um novo ambiente de execução nos navegadores.
  • Experiência do desenvolvedor:o novo design depende de cabeçalhos, que são comumente usados e conhecidos pelos desenvolvedores, ao contrário dos worklets. Ela também se alinha de perto à plataforma da API para registro de origem, facilitando o aprendizado e o uso da API.
  • Adopção:o novo design permite que mais sistemas de medição usem relatórios agregados. Muitas soluções de medição são somente HTTP: elas dependem de solicitações de imagem (solicitações de pixel) que não exigem acesso ao JavaScript. No entanto, como a abordagem de worklet exigia acesso ao JavaScript, talvez fosse difícil migrar de alguns sistemas de medição.
  • Robustez:o novo design ajuda a mitigar a perda de dados porque é mais fácil de integrar com a semântica keepalive, por exemplo, se um clique ou visualização for registrado quando um usuário sair de uma página.

Como funciona o mecanismo sem worklets?

Esse mecanismo declarativo é baseado em cabeçalhos HTTP, assim como o registro de origem no nível do evento e o cabeçalho do acionador de atribuição. Mais detalhes sobre isso nas próximas seções.

Participar da discussão pública

Problema 194

Registro de origem com base em cabeçalho (relatórios agregáveis)

Um novo mecanismo é proposto para registrar uma origem em um relatório agregável. Esse mecanismo é o mesmo do registro de origem no nível do evento.

Somente o nome do cabeçalho é diferente: Attribution-Reporting-Register-Aggregatable-Source.

Saiba mais na explicação técnica

Registro de origem de atribuição

Acionador de atribuição baseado em cabeçalho (relatórios agregáveis)

Um novo mecanismo é proposto para registrar uma fonte em um relatório agregável. Esse mecanismo é o mesmo do acionador de atribuição no nível do evento.

Somente o nome do cabeçalho é diferente: Attribution-Reporting-Register-Aggregatable-Trigger-Data.

Saiba mais na explicação técnica

Registro do acionador de atribuição

Novos recursos

Relatórios de terceiros (relatórios de eventos e agregáveis)

O que vai mudar e por quê?

Dois aspectos da nova proposta ajudam a oferecer suporte aos casos de uso de relatórios de terceiros:

  • Opcionalmente, as adtechs podem redirecionar solicitações de rede para outros servidores de adtechs, o que permite que essas outras adtechs realizem o próprio registro de acionador e de origem. Essa é uma maneira comum de configurar terceiros hoje. Isso facilita a adoção da API, entre outras em sistemas de relatórios de terceiros.
  • As origens de relatórios, geralmente adtechs, não compartilham mais a maioria dos limites de privacidade. Isso é útil em casos em que várias adtechs trabalham com os mesmos editores ou anunciantes.

Como funcionam os relatórios de terceiros?

Na nova proposta, o registro e o acionador da origem baseados em resposta dependem de cabeçalhos HTTP. Uma adtech pode aproveitar os redirecionamentos HTTP para essas solicitações.

Se uma solicitação de clique/visualização em um site do editor (registro de origem) for redirecionada posteriormente para várias partes, cada uma dessas partes poderá registrar essa visualização ou clique (evento de origem).
Da mesma forma, uma adtech pode redirecionar uma solicitação de atribuição específica feita em um site do anunciante, permitindo que várias outras partes registrem uma conversão (gatilho de atribuição).

Cada parte pode acessar os relatórios separados e configurá-los com dados separados.

Registrar vários acionadores sem redirecionamentos

Também é possível registrar vários acionadores de atribuição sem usar redirecionamentos, adicionando vários elementos de pixel no lado da conversão (um por acionador).

Participar da discussão pública

Problema 91 Problema 261

Medição de visualização (relatórios de eventos e agregáveis)

O que vai mudar e por quê?

Na nova proposta, a medição de visualização e de clique funcionam de forma unificada:

  • registerattributionsrc, o atributo específico da visualização que instruiu o navegador a registrar visualizações com cliques, não faz mais parte da proposta.
  • Os mecanismos de privacidade agora são unificados entre cliques e visualizações. Confira os detalhes em Ruído e transparência.

Essa mudança foi proposta para se alinhar ao novo mecanismo de registro baseado em cabeçalho. Ela também simplifica a experiência do desenvolvedor ao oferecer suporte à medição de cliques e de visualização.

Como funciona a medição de visualização?

A medição de visualização e a de cliques dependem do registro com base no cabeçalho.

Saiba mais na explicação técnica

Relatórios no nível do evento (para cliques e visualizações)

Participar da discussão pública

Problema 261

Depuração / análise de desempenho (relatórios de eventos e agregáveis)

O que vai mudar e por quê?

Um mecanismo de depuração foi adicionado à proposta para ajudar os desenvolvedores a detectar bugs e comparar a performance dos Relatórios de atribuição com as soluções de medição baseadas em cookies.

Diagrama do novo sistema de depuração baseado em cookies

Como funciona a depuração?

O registro de origem e de acionador aceita um novo parâmetro debug_key, um número inteiro não assinado de 64 bits, ou seja, um número grande.

Se um relatório for criado com chaves de depuração de origem e acionador e um cookie Samesite=None ar_debug=1 estiver presente no cookie jar da origem do relatório no momento do registro da origem e do acionador, um relatório de depuração (JSON) será enviado para um endpoint .well-known/attribution-reporting/debug:

{
  "source_debug_key": 1234567890987,
  "trigger_debug_key": 4567654345028
}

Os relatórios agregáveis e no nível do evento também vão incluir esses dois novos parâmetros para que possam ser associados ao relatório de depuração correto.

Saiba mais na explicação técnica

Opcional: relatórios de depuração estendidos

Participar da discussão pública

Problema 174

Recursos de filtragem (relatórios de eventos e agregáveis)

O que vai mudar e por quê?

Como eles oferecem suporte a casos de uso importantes no atual ecossistema de publicidade, vários deles agora serão compatíveis com relatórios no nível do evento e agregáveis:

  • Filtragem de conversões:filtre uma conversão com base nas informações da origem. Por exemplo, selecione diferentes dados de gatilho (dados de conversão) para cliques e visualizações de anúncios.
  • Incompatibilidade de atribuição:filtre conversões que foram atribuídas incorretamente. Esse é um tipo específico de filtragem de conversões. Por exemplo, filtrar conversões que são associadas ao clique/visualização de anúncio errado devido ao eTLD+1 na API.

Como funcionam os recursos de filtragem? (para relatórios de eventos)

Um campo source_data opcional no objeto JSON do lado da origem pode definir itens que serão usados posteriormente pelo navegador no momento da conversão para aplicar a lógica de filtragem.

  {
    source_event_id: "267630968326743374",
    destination: "https://toasters.example",
    expiry: "604800000"
    source_data: {
      conversion_subdomain: ["electronics.megastore"
                              "electronics2.megastore"],
      product: "198764",
      // Note that "source_type" will be automatically generated as one of {"navigation", "event"}
    }
  }

O registro de acionadores agora aceita um cabeçalho opcional Attribution-Reporting-Filters.

Cabeçalho de resposta HTTP Attribution-Reporting-Filters:

{
  "conversion_subdomain": "electronics.megastore",
  "directory": "/store/electronics"
}

Como alternativa, o cabeçalho Attribution-Reporting-Register-Event-Trigger pode ser estendido com um campo filters para fazer a filtragem seletiva e definir trigger_data com base em source_data.

Se as chaves no JSON dos filtros corresponderem às chaves em source_data, o acionador será
completamente ignorado se a interseção estiver vazia.

Saiba mais na explicação técnica

Filtros de atribuição opcionais

Participar da discussão pública

Problema 194
Problema 201

Mudanças na proteção de privacidade

Ruído e transparência (relatórios de eventos e agregáveis)

O que vai mudar e por quê?

Na nova proposta, um dos mecanismos de privacidade para relatórios foi aprimorado: os relatórios estão sujeitos a resposta aleatória.
Isso significa que algumas conversões reais serão informadas corretamente e, em uma determinada porcentagem do tempo, algumas conversões reais serão suprimidas ou algumas conversões falsas serão adicionadas.

Essa nova técnica tem alguns benefícios:

  • Ele unifica o mecanismo de privacidade para cliques e visualizações.
  • É mais fácil analisar do que um mecanismo em que os dados de gatilho (dados de conversão) e o ruído de link de gatilho-origem seriam separados.
  • Ele configura um framework de privacidade que, com as configurações de ruído corretas, pode garantir que nenhuma parte possa confiar na API para saber com certeza se um usuário individual converteu (ou não) para um determinado anúncio.

Esse novo mecanismo substitui o anterior, em que 5% das vezes os dados de gatilho (dados de conversão) eram substituídos por um valor aleatório.

Além disso, o valor da probabilidade de resposta aleatória foi adicionado ao corpo do relatório (campo randomized_trigger_rate). Esse campo especifica a probabilidade (0 a 1) de que uma origem esteja sujeita a uma resposta aleatória.

Isso tem dois benefícios principais:

  • Ele torna o comportamento do navegador transparente para as partes que vão receber os relatórios (normalmente, adtechs).
  • Isso é útil para um futuro em que a API terá suporte em navegadores: diferentes navegadores podem decidir aplicar diferentes níveis de ruído, dependendo dos objetivos de privacidade, e as partes que vão processar o relatório precisam ter visibilidade sobre isso.

Como o ruído funciona?

Na nova proposta, no momento em que uma origem é registrada (ou seja, quando um clique ou visualização de anúncio é registrado), o navegador decide aleatoriamente se vai atribuir as conversões e enviar relatórios para esse clique/visualização de anúncio ou se vai gerar uma saída falsa.

A saída falsa pode ser:

  • Nenhum relatório, mesmo que o usuário faça uma conversão.
  • Um ou vários relatórios falsos, independentemente de a conversão do usuário.

Nos relatórios falsos, os dados de gatilho (dados de conversão) são aleatórios: um valor aleatório de 3 bits para cliques (qualquer número entre 0 e 7) e um valor aleatório de 1 bit para visualizações (0 ou 1).

Assim como os relatórios reais, os falsos não são enviados imediatamente após a conversão do usuário. Elas são enviadas no final de uma janela de relatórios aleatória.

Há três janelas de geração de relatórios para cliques (dois, sete ou 30 dias após o clique). Cada relatório falso é atribuído aleatoriamente a uma das janelas de relatórios.

Além disso, como a proposta anterior já indicou, a ordem dos relatórios dentro de uma janela é aleatória.

Saiba mais na explicação técnica

Exemplos de conversões falsas com ruído

Participar da discussão pública

Problema 84
Problema 273

Limitações de relatórios (relatórios de eventos e agregáveis)

Limites de origem dos relatórios

O que vai mudar e por quê?

A nova proposta limita explicitamente quantas partes podem medir eventos entre dois sites.

  • O número máximo de origens de relatórios exclusivas (geralmente adtechs) que podem registrar fontes por {editor, anunciante} é limitado a 100 por 30 dias. Esse contador vai ser incrementado para cada clique ou visualização do anúncio (evento de origem), mesmo aqueles que não são atribuídos.
  • O número máximo de origens de relatórios exclusivas (geralmente adtechs) que podem enviar relatórios por {publisher, advertiser} é limitado a 10 a cada 30 dias. Esse contador vai ser incrementado para cada conversão atribuída.

Esses limites são altos o suficiente para não limitar a capacidade de nenhum ator de medir conversões, mas baixos o suficiente para ajudar a reduzir algumas formas de abuso de API.

Período de espera / limites de taxa dos relatórios

O que vai mudar e por quê?

O período de espera para relatórios é um mecanismo de privacidade que limita a quantidade total de informações enviadas por um usuário usando essa API em um determinado período.

Na nova proposta, 100 relatórios por {site de origem, destino, origem do relatório} (geralmente {editor, anunciante, adtech}) podem ser programados em 30 dias.

Além desse limite, o navegador vai parar de programar relatórios que correspondem a esse {site de origem, destino, origem do relatório} (normalmente {editor, anunciante, adtech}), até que a contagem de relatórios de 30 dias caia abaixo de 100 para esse {site de origem, destino, origem do relatório}.

Saiba mais na explicação técnica

Período de espera / limites de taxa dos relatórios

Limite de destino (somente relatórios de eventos)

O que vai mudar e por quê?

O limite de destino foi modificado para incluir a origem de relatórios (geralmente, uma adtech) no escopo: 100 destinos pendentes únicos (geralmente, sites de anunciantes ou sites em que as conversões devem ocorrer) são permitidos por {publisher, adtech}.

Isso é uma proteção de privacidade para limitar a reconstrução do histórico de navegação.

Saiba mais na explicação técnica

Limitar o número de destinos exclusivos cobertos por fontes pendentes

Todos os recursos

A imagem do cabeçalho é de Diana Polekhina no Unsplash.