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 a anúncios (um clique ou uma visualização) a que 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 regiões geográficas.
  • 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 neste documento, você pode registrar origens (impressões ou cliques de anúncios) às quais 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 ligação
  • XMLHttpRequest
  • window.open ligação

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. Siga as etapas completas. Aqui está o resumo:

  1. Inicie 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ê verá nas seções a seguir.

  2. Conclua o registro da fonte respondendo com o cabeçalho de registro. Ao receber essa solicitação, responda com o cabeçalho Attribution-Reporting-Register-Source. Nesse cabeçalho, especifique a configuração desejada do Attribution Reporting. 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 para 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 JavaScript para registrar origens, talvez seja 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 a API Attribution Reporting. Se você usar attributionsrc, o navegador enviará o cabeçalho Attribution-Reporting-Eligible. Também é útil para medição de app para Web: se attributionsrc estiver presente, o navegador enviará o cabeçalho Attribution-Reporting-Support.

Método de registro Original
Tag <a> (origem da navegação)
attributionsrc é obrigatório.
Tag <img> (origem do evento)
attributionsrc é obrigatório.
Tag <script> (origem do evento)
attributionsrc é obrigatório.
fetch ligação A opção attributionReporting é obrigatória.
XMLHttpRequest A opção attributionReporting é obrigatória.
window.open ligação (origem da navegação)
attributionsrc é obrigatório.

Etapa 1: iniciar o registro da origem

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 em que você quer medir impressões ou cliques:

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

Analise o exemplo de código para saber mais.

Como usar um script

Chame window.open() com attributionsrc:

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

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

Em vez de adicionar attributionsrc sozinho, para uma imagem ou um script é possível especificar um único valor de URL:

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

No caso de JavaScript, se você fornecer um valor a attributionsrc, codifique esse URL caso ele contenha caracteres especiais, como =, que fazem com que o parâmetro seja 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 usar uma lista de URLs separada por espaços, conforme ilustrado aqui com uma tag <a>:

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

ou, como é o caso, 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 único URL. Além disso, é possível usar uma lista de URLs separada por espaços.

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

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

Por exemplo, se for necessário registrar origens para cliques em um elemento âncora, talvez você não esteja no controle do destino. Nesse caso, convém enviar o cabeçalho de registro de origem como uma resposta a uma solicitação separada da navegação e que você pode controlar totalmente. Ao especificar um valor explícito para attributionsrc, você instrui o navegador a fazer essa solicitação extra e configura o destino.

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, você pode usar JavaScript fetch() ou XMLHttpRequest().

Com uma imagem

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

Com um roteiro

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

Se preferir, especifique um valor de URL para attributionsrc da mesma maneira que para cliques, ou seja, para uma imagem ou script, é possível definir os URLs de 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()

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

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

// Optionally set keepalive to ensure 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 o cabeçalho (cliques e visualizações)

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

Analise o exemplo de código para saber mais.

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

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 usar a string, o cabeçalho terá a seguinte aparência:

{"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.