Registrar fontes de atribuição

Saiba como registrar origens para atribuir cliques e visualizações aos eventos adequados.

Uma fonte de atribuição é um evento relacionado a um anúncio (um clique ou uma visualização) a que uma adtech pode anexar os seguintes tipos de informações:

• Dados contextuais de relatórios, como o ID do criativo do anúncio, informações sobre a campanha ou a região geográfica.
• Um destino de conversão, como o site em que você espera que o usuário faça uma conversão.

Ao seguir as etapas deste documento, você pode registrar origens (impressões ou cliques de anúncios) a que o navegador atribui conversões.

Métodos de registro

Para registrar fontes de atribuição, use elementos HTML ou chamadas JavaScript:

• Tag <a>
• Tag <img>
• Tag <script>
• fetch chamada
• XMLHttpRequest
• window.open chamada

Isso gera solicitações de rede que você responde com um cabeçalho de resposta HTTP de registro de origem.

Registrar fontes para cliques ou visualizações

Para registrar uma fonte de atribuição de cliques ou visualizações, siga as etapas descritas aqui. Confira as etapas completas. Confira o resumo:

1. Inicie o registro da fonte. Use um elemento HTML ou uma chamada JavaScript para fazer uma solicitação. Essa etapa é diferente para cliques e visualizações, como você vai notar nas seções a seguir.

2. Conclua o registro da origem respondendo com o cabeçalho de registro da origem. Ao receber essa solicitação, responda com o cabeçalho Attribution-Reporting-Register-Source. Nesse cabeçalho, especifique a configuração escolhida de Relatórios de atribuição. Essa etapa é igual para cliques e visualizações.

   Exemplo de relatórios de resumo:

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   Exemplo de relatórios no nível do evento:

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

Atributos obrigatórios e opcionais

Ao usar elementos HTML ou fazer chamadas JavaScript para registrar fontes, talvez seja necessário usar attributionsrc ou attributionReporting. Consulte a tabela a seguir para saber quando eles são obrigatórios.

Quando attributionsrc é opcional, o uso dele indica que a solicitação está qualificada para os relatórios de atribuição. Se você usar attributionsrc, o navegador enviará o cabeçalho Attribution-Reporting-Eligible. Também é útil para a medição de app para Web: se attributionsrc estiver presente, o navegador enviará o cabeçalho Attribution-Reporting-Support.

Etapa 1: iniciar o registro da origem

A etapa 1 é diferente para cliques e visualizações.

Para registrar uma fonte de atribuição de um clique, use uma tag <a> ou JavaScript window.open().

Como usar uma âncora

Adicione attributionsrc às tags <a> atuais para medir impressões ou cliques:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Confira o código de exemplo para mais informações.

Usar um script

Ligue para window.open() com attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Para ser considerado, esse método precisa ser chamado em até cinco segundos após a interação do usuário.

Em vez de adicionar attributionsrc por si só, para uma imagem ou script, você pode especificar um único valor de URL:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

No caso do JavaScript, se você atribuir um valor a attributionsrc, codifique o URL caso ele contenha caracteres especiais, como =, que fariam com que o parâmetro fosse analisado incorretamente.

Codifique da seguinte forma:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc também pode receber uma lista de URLs separados por espaços, como ilustrado aqui com uma tag <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

ou como está aqui usando window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

Nesses casos, os dois URLs recebem solicitações attributionsrc qualificadas para origem de navegação (solicitações que incluem o cabeçalho Attribution-Reporting-Eligible).

attributionsrc com ou sem um valor

Como vimos antes, é possível especificar attributionsrc sem um URL. Também é possível especificar um único URL. Além disso, você pode usar uma lista de URLs separada por espaços.

O uso de URLs faz com que o navegador inicie uma solicitação de busca keepalive separada, uma para cada URL, que inclui o cabeçalho de solicitação Attribution-Reporting-Eligible.

Isso é útil se você quiser fazer o registro da origem respondendo a uma solicitação separada da principal do elemento.

Por exemplo, se você precisar registrar fontes para cliques em um elemento de âncora, talvez não tenha controle sobre o destino. Nesse caso, você vai querer uma configuração em que envie o cabeçalho de registro de origem como uma resposta a uma solicitação separada da navegação e que possa controlar completamente. Ao especificar um valor explícito para attributionsrc, você está instruindo o navegador a fazer essa solicitação extra e configurando o destino dela.

Para registrar uma fonte de atribuição para uma visualização, use uma tag de imagem ou script a que você vai adicionar o atributo attributionsrc.

Como alternativa, use JavaScript fetch() ou XMLHttpRequest().

Com uma imagem

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Com um script

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Se quiser, especifique um valor de URL para attributionsrc da mesma forma que para cliques. Ou seja, para uma imagem ou script , defina o URL ou URLs attributionsrc da seguinte maneira:

Com um único URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Com uma lista de URLs:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Como usar fetch() ou XMLHttpRequest()

Esse código simula o que uma solicitação HTML com attributionsrc faria:

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Etapa 2: responder com cabeçalho (cliques e visualizações)

A próxima etapa para cliques e visualizações é responder com o cabeçalho Attribution-Reporting-Register-Source.

Confira o código de exemplo para mais informações.

Ao receber a solicitação do navegador no servidor, responda e inclua na resposta o cabeçalho Attribution-Reporting-Register-Source.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Depois de transformado em string, o cabeçalho fica assim:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Próximas etapas

Saiba como registrar gatilhos de atribuição.