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 chamada
  • XMLHttpRequest
  • window.open chamada

Isso gera solicitações de rede que você responde com uma origem de registro do certificado.

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 um 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 a fonte. 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

Conforme você usa elementos HTML ou faz chamadas JavaScript para registrar fontes, você pode ser necessário usar attributionsrc ou attributionReporting. Consulte a tabela a seguir para saber quando elas são obrigató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 envia a Cabeçalho Attribution-Reporting-Eligible. Também é útil para transações de app para a Web medição: se attributionsrc estiver presente, o navegador enviará o Cabeçalho Attribution-Reporting-Support.

Método de registro Origem
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 chamada A opção attributionReporting é obrigatório.
XMLHttpRequest A opção attributionReporting é obrigatório.
window.open chamada (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 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ê atribuir um valor a attributionsrc, verifique se para codificar esse URL caso ele contenha caracteres especiais como = que faria com que o parâmetro não fosse analisado corretamente.

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 o attributionsrc qualificado 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 a solicitação Attribution-Reporting-Eligible cabeçalho.

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

Por exemplo, se você precisar registrar origens de cliques em um elemento âncora, talvez você não esteja no controle do destino. Nesse caso, convém uma configuração em que você envia o cabeçalho de registro de origem como resposta a uma solicitação separado da navegação e que você pode controlar totalmente. De especificando um valor explícito para attributionsrc, você instrui o navegador para fazer essa solicitação extra e configurar seu 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>

Opcionalmente, você pode especificar um valor de URL para attributionsrc da mesma forma que para Cliques Ou seja, no caso de uma imagem ou script , é possível definir o URL attributionsrc ou os URLs da seguinte forma:

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 em sua resposta ao 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 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.