Registrar fontes de atribuição

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

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

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

Ao seguir as etapas deste documento, você pode registrar as origens (impressões de anúncios ou cliques) às quais o navegador atribui as 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 origens de cliques ou visualizações

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

1. Iniciar o registro da origem. 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 próximas seções.

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 de relatórios de atribuição escolhida. Essa etapa é a mesma 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 de eventos:

   {
     "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 de JavaScript para registrar fontes, pode ser necessário usar attributionsrc ou attributionReporting. Consulte a tabela a seguir para saber quando eles são necessários.

Quando attributionsrc é opcional, o uso dele indica que a solicitação está qualificada para Relatórios de atribuição. Se você usar attributionsrc, o navegador vai enviar o cabeçalho Attribution-Reporting-Eligible. Ele também é útil para 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 fonte

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

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

Como usar uma âncora

Adicione attributionsrc às tags <a> atuais para as quais você quer medir impressões ou cliques:

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

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

Usar um script

Chame window.open() com attributionsrc:

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

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

Em vez de adicionar attributionsrc sozinho, 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 esse URL caso ele contenha caracteres especiais, como =, que fariam com que o parâmetro fosse analisado incorretamente.

Codifique da seguinte maneira:

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 a origem de navegação (solicitações que incluem o cabeçalho Attribution-Reporting-Eligible).

attributionsrc com ou sem um valor

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

O uso de URLs faz com que o navegador inicie uma solicitação de busca de 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 fonte respondendo a uma solicitação separada da principal do elemento.

Por exemplo, se você precisar registrar origens 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 você envia o cabeçalho de registro de origem como uma resposta a uma solicitação separada da navegação e que você pode controlar completamente. Ao especificar um valor explícito para attributionsrc, você instrui o navegador a fazer essa solicitação extra e configurar o destino dela.

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

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

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>

Opcionalmente, você pode especificar um valor de URL para attributionsrc da mesma forma que para cliques. Ou seja, para uma imagem ou script , você pode definir o URL ou os URLs de attributionsrc assim:

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 exemplo de código para mais informações.

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

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 ser convertido 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 acionadores de atribuição.