A proposta da API Attribution Reporting passou por uma série de mudanças para atender aos comentários da comunidade, desde mudanças no mecanismo da API até novas funcionalidades.
Registro de alterações
- 7 de fevereiro de 2022: adição da seção sobre o redirecionamento do acionador de cabeçalho.
- 27 de janeiro de 2022: artigo publicado pela primeira vez.
Qual é o público desta postagem?
Esta postagem é para você:
- Se você já conhece a API, por exemplo, observando ou participando das discussões no repositório 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 um experimento em produção.
Se você está começando a usar essa API e/ou ainda não fez testes, vá diretamente para a introdução à API.
Migração à frente
Depois que essas mudanças forem implementadas no Chrome: se você usar relatórios de eventos da API Attribution Reporting em uma demonstração ou um experimento em produção (teste de origem), vai ser necessário editar seu código para que a API continue funcionando. Você também pode usar os novos recursos.
Este artigo também lista as mudanças para 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 agregáveis
Os relatórios agregados agora são chamados de relatórios de resumo.
Os relatórios de resumo são o resultado final da agregação de vários relatórios agregáveis, anteriormente chamados de contribuições ou contribuições de histograma.
Mudanças no mecanismo da API
Registro de origem com base em cabeçalho (relatórios de eventos)
O que está mudando 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
com parâmetros específicos dos 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 no lado do cliente: nas tags âncora como atributos HTML ou como argumentos de uma chamada baseada em JS. Os parâmetros precisam ser conhecidos no momento do clique ou da visualização.
Na nova proposta, o valor desses parâmetros é definido no servidor de adtechs.
Isso tem várias vantagens, especialmente 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 é registrada no escopo dela. Isso reduz parcialmente as preocupações com fraudes, porque um navegador genuíno nunca registrará uma fonte sem a permissão da origem do relatório.
Como funciona o registro de fonte?
- 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 enviará uma solicitação. Essa solicitação vai incluir um novo cabeçalho HTTPAttribution-Reporting-Source-Infocom um valornavigationouevent,que especifica se a origem foi um clique ou uma visualização, respectivamente. - Ao receber essa solicitação, o servidor de rastreamento de cliques/visualizações precisa responder com um cabeçalho HTTP,
Attribution-Reporting-Register-Source, que contém os parâmetros de atribuição desejados. 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
Registro de fontes de atribuição
Participar da discussão pública
Acionador de atribuição com base no cabeçalho (relatórios de eventos)
O que está mudando e por quê?
Assim como o registro de cliques ou visualizações, a nova proposta muda o acionador de atribuição, quando uma
adtech instrui o navegador a registrar uma conversão, para uma abordagem baseada no cabeçalho.
Esse mecanismo está alinhado com o registro de origem baseado 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.
A lógica é uma questão de permissões: na proposta anterior, o site do lado do acionador (normalmente,
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 poderia enviar uma solicitação para uma parte
que acionaria uma atribuiçã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 de editor), há um controle de toda a página via
Permissions-Policy e um controle de todo o elemento via attributionsrc.
Como o acionador de atribuição funciona?
Ao receber uma solicitação de pixel e decidir que ele precisa ser categorizado como conversão, a adtech
precisa responder com um novo cabeçalho
HTTP Attribution-Reporting-Register-Event-Trigger.
O valor desse cabeçalho especifica como tratar o evento acionador, como um objeto JSON. 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 tornar a resposta que contém Attribution-Reporting-Register-Event-Trigger uma resposta de redirecionamento.
Assim, terceiros podem observar o evento de conversão e instruir o navegador a atribuí-lo.
O redirecionamento é opcional. Ele não é necessário quando uma adtech e um terceiro têm pixels na página.
Mais detalhes em Relatórios de terceiros.
Saiba mais na explicação técnica
Participar da discussão pública
Nenhum worklet (relatórios agregáveis)
O que está mudando e por quê?
Na proposta anterior de relatórios agregáveis, o acesso JavaScript era necessário para invocar um worklet, um mecanismo baseado em JavaScript, que geraria esses relatórios.
Na nova proposta, nenhuma worklet é necessária. Em vez disso, uma adtech definiria de maneira declarativa, por 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, é bastante mais simples, porque não exige 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 amplamente conhecidos pelos desenvolvedores, ao contrário dos worklets. Ela também se alinha estreitamente à superfície da API para registro de fonte, facilitando o aprendizado e o uso da API.
- Adoção:o novo design permite que mais sistemas de medição atuais usem relatórios agregáveis. Muitas soluções de métricas são apenas HTTP: elas dependem de solicitações de imagem, ou seja, solicitações de pixels, que não exigem acesso ao JavaScript. No entanto, como a abordagem de worklet exigia acesso a JavaScript, pode ser difícil migrar de alguns sistemas de medição atuais.
- Robustez:o novo design ajuda a reduzir a perda de dados porque é mais fácil de integrar
com a semântica
keepalive, por exemplo, se um clique ou uma visualização é registrada quando um usuário está saindo de uma página.
Como funciona o mecanismo sem worklet?
Esse mecanismo declarativo é baseado em cabeçalhos HTTP, assim como o registro da fonte 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
Registro de fonte com base em cabeçalho (relatórios agregáveis)
Foi proposto um novo mecanismo para registrar uma fonte em um relatório agregável. Esse mecanismo é o mesmo que o registro de origem no evento.
Apenas o nome do cabeçalho é diferente: Attribution-Reporting-Register-Aggregatable-Source.
Saiba mais na explicação técnica
Registro da fonte de atribuição
Acionador de atribuição com base no cabeçalho (relatórios agregáveis)
Foi proposto um novo mecanismo para registrar uma fonte em um relatório agregável. Esse mecanismo é o mesmo que o acionador de atribuição no nível do evento.
Apenas 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 está mudando e por quê?
Dois aspectos da nova proposta vão ajudar a oferecer um suporte melhor aos casos de uso de relatórios de terceiros:
- As adtechs podem redirecionar solicitações de rede para outros servidores, o que permite que essas outras adtechs realizem o próprio registro de fonte e acionador. Hoje, essa é uma maneira comum de configurar terceiros. Isso facilita a adoção da API, entre outras opções 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 oferece suporte a casos de uso 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 com base em resposta dependem de cabeçalhos HTTP. Uma adtech pode usar redirecionamentos HTTP para essas solicitações.
Se uma solicitação de clique/visualização no site de um editor (registro da fonte) for redirecionada posteriormente a várias partes, cada uma delas poderá registrar essa visualização ou esse clique (evento de origem).
Da mesma forma, uma adtech pode redirecionar uma solicitação de atribuição específica feita de um site de adiversor,
permitindo que várias outras partes registrem uma conversão (acionador de atribuição).
Cada parte pode acessar 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 na conversão (um por acionador).
Participar da discussão pública
Medição de visualizações (relatórios de eventos e agregáveis)
O que está mudando e por quê?
Na nova proposta, a medição de visualização e de cliques funcionam de maneira unificada:
registerattributionsrc, o atributo específico da visualização que instruiu o navegador a registrar visualizações junto com cliques, não faz mais parte da proposta.- Agora, os mecanismos de privacidade estão unificados nas opções de clique e visualização. Saiba mais sobre isso em Ruído e transparência.
Essa mudança foi proposta para estar alinhada ao novo mecanismo de registro baseado em cabeçalho. Ela também simplifica a experiência do desenvolvedor quando pretende oferecer suporte à medição de cliques e visualizações.
Como funciona a medição de conversão de visualização?
A medição de visualizações e de cliques dependem do registro baseado em cabeçalho.
Saiba mais na explicação técnica
Relatórios de evento (para cliques e visualizações)
Participar da discussão pública
Depuração / análise de desempenho (relatórios agregáveis e de eventos)
O que está mudando e por quê?
Um mecanismo de depuração foi adicionado à proposta para ajudar os desenvolvedores a detectar bugs, além de comparar o desempenho do Relatório de atribuição com as soluções de métricas atuais com base em cookies.
Como funciona a depuração?
Os registros do acionador e da fonte aceitam 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 fonte e acionador e se um cookie Samesite=None ar_debug=1
estiver presente no cookie jar da origem do relatório no momento do registro do acionador e da fonte, 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 de 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
Recursos de filtragem (relatórios de eventos e agregáveis)
O que está mudando e por quê?
Como eles oferecem suporte a casos de uso importantes no ecossistema de publicidade atual, vários casos de uso agora têm suporte em relatórios agregáveis e de evento:
- Filtragem de conversões:filtra uma conversão com base nas informações da origem. Por exemplo, selecione dados de acionadores (dados de conversão) diferentes para visualizações e cliques em anúncios.
- Atribuição incompatível:filtra as conversões que foram atribuídas incorretamente. Esse é um tipo específico de filtragem de conversões. Por exemplo, filtre as conversões que são correspondidas ao clique/visualização errada do anúncio devido ao escopo de destino "etld+1" na API.
Como funcionam os recursos de filtragem? (para relatórios a nível de evento)
Um campo source_data opcional no objeto JSON no lado da origem pode definir itens que vão ser
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 do acionador 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 para definir trigger_data com base em source_data.
Se as chaves nos filtros JSON corresponderem às chaves em source_data, o gatilho será
totalmente 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
Mudanças na proteção de privacidade
Ruído e transparência (relatórios agregáveis e de eventos)
O que está mudando e por quê?
Na nova proposta, um dos mecanismos de privacidade para relatórios foi aprimorado: os relatórios estão
sujeitos a uma resposta aleatória.
Isso significa que algumas conversões reais serão informadas corretamente e, em determinada porcentagem do tempo, algumas conversões reais serão suprimidas ou outras falsas serão adicionadas.
Essa nova técnica tem alguns benefícios:
- Ele unifica o mecanismo de privacidade para cliques e visualizações.
- É mais simples entender do que um mecanismo em que os dados do acionador (dados de conversão) e o ruído do link da origem do acionador seriam separados.
- Ela define uma estrutura de privacidade que pode, com as configurações de ruído corretas, garantir que nenhuma parte possa confiar na API para saber com certeza se um usuário individual fez uma conversão (ou não) para um determinado anúncio.
Esse novo mecanismo substitui o anterior, em que, em 5% das vezes, os dados do acionador (dados de conversão) eram substituídos por um valor aleatório.
Além disso, o valor de 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 uma fonte estar sujeita a resposta aleatória.
Isso tem dois benefícios principais:
- Ela torna o comportamento do navegador transparent para as partes que vão receber os relatórios, geralmente, adtechs.
- Ela será útil em um futuro em que a API teria suporte em todos os navegadores: diferentes navegadores podem decidir aplicar diferentes níveis de ruído dependendo das metas de privacidade de cada um, e as partes responsáveis pelo relatório vão precisar de visibilidade sobre isso.
Como o ruído funciona?
Na nova proposta, no momento em que uma origem é registrada (ou seja, um clique no anúncio ou uma visualização é registrada), o navegador decide aleatoriamente se ele vai atribuir conversões de forma verdadeira e enviar relatórios sobre esse clique/visualização do anúncio ou se ele vai gerar uma saída falsa.
A saída simulada pode ser:
- Nenhum relatório, independentemente de o usuário realizar a conversão.
- Um ou vários relatórios falsos, independentemente da conversão do usuário.
Nos relatórios falsos, os dados do acionador (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).
Como os relatórios reais, os relatórios falsos não são enviados imediatamente após a conversão do usuário. Eles são enviados no final de uma janela de relatório aleatória.
Há três janelas de relatórios para cliques (2, 7 dias ou 30 dias após o clique). Cada relatório falso é atribuído aleatoriamente a uma das janelas.
Separadamente, como já mencionado na proposta anterior, 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
Limitações de relatórios (relatórios de eventos e agregáveis)
Limites de origem dos relatórios
O que está mudando e por quê?
A nova proposta limita explicitamente quantas partes podem medir eventos entre dois sites.
- Propomos que o número máximo de origens de relatórios exclusivas (geralmente adtechs) que podem registrar fontes por {publisher, advertiser} seja limitado a 100 a cada 30 dias. Esse contador será incrementado para cada clique ou visualização no anúncio (evento de origem), mesmo para aqueles que não foram atribuídos.
- Propomos que o número máximo de origens de relatórios exclusivas (geralmente adtechs) que podem enviar relatórios por {publisher, advertiser} seja limitado a 10 a cada 30 dias. Esse contador será incrementado para cada conversão atribuída.
Esses limites precisam ser altos o suficiente para não limitar a capacidade de qualquer agente medir as conversões, mas baixos o suficiente para ajudar a atenuar algumas formas de abuso da API.
Período de espera / limites de taxa para relatórios
O que está mudando e por quê?
O período de espera de relatórios é um mecanismo de privacidade que limita a quantidade total de informações enviadas por essa API em um determinado período para um usuário.
Na nova proposta, é possível programar 100 relatórios por {site de origem, destino, origem do relatório} (geralmente {publisher, advertiser, adtech}) para ser programado para mais de 30 dias.
Além desse limite, o navegador deixará de programar relatórios que correspondam a este {site de origem, destino, origem do relatório} (geralmente {publisher, advertiser, adtech}) até que a contagem contínua de relatórios de 30 dias fique abaixo de 100 para esse {site de origem, destino, origem de relatórios}.
Saiba mais na explicação técnica
Tempo de espera para relatórios / limites de taxa
Limite de destino (somente relatórios de eventos)
O que está mudando e por quê?
O limite de destino foi modificado para incluir a origem do relatório (normalmente, uma adtech) no escopo: são permitidos 100 destinos pendentes únicos (geralmente, sites de anunciantes ou sites em que as conversões são esperadas) de acordo com {publisher, adtech}.
Essa é uma proteção de privacidade para limitar a reconstrução do histórico de navegação.
Saiba mais na explicação técnica
Limitação do número de destinos exclusivos cobertos por fontes pendentes
Todos os recursos
- Consulte API Attribution Reporting.
- Leia o artigo O que você precisa saber sobre a API.
A imagem do cabeçalho é da Diana Polekhina no Unsplash (links em inglês).