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 (clique ou visualização) em 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ão geográfica. - Um destino de conversão, como o site em que você espera que o usuário faça uma conversão.

Siga as etapas neste documento para registrar origens, como impressões de anúncios ou cliques, à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

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

Registrar origens para 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 a seguir. 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ê vai perceber nas próximas seções.

  2. Conclua o registro da fonte respondendo com o cabeçalho correspondente. Ao receber essa solicitação, responda com o cabeçalho Attribution-Reporting-Register-Source. Nesse cabeçalho, especifique a configuração desejada do Relatório de atribuição. Esta 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 JavaScript para registrar origens, talvez seja necessário usar attributionsrc ou attributionReporting. Consulte a tabela a seguir para ver detalhes sobre quando eles são necessários.

Quando attributionsrc é opcional, o uso 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. Ele também é útil para medições de app para a Web: se attributionsrc estiver presente, o navegador enviará o cabeçalho Attribution-Reporting-Support.

Método de registro Origem
Tag <a> (origem de navegação)
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() (origem de navegação)
O parâmetro attributionsrc é obrigatório.

Etapa 1: iniciar o registro da fonte

A etapa 1 é diferente para cliques e visualizações. Abra as guias correspondentes de cada um.

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

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>

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

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 5 segundos após a interação do usuário.

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

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

No caso do JavaScript, se você fornecer um valor para attributionsrc, codifique esse URL caso ele contenha caracteres especiais, como "=", que causariam a análise incorreta do parâmetro.

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 âncora:

<!-- With an anchor tag -->
<a href=... attributionsrc="https://a.example/register-source 
  https://b.example/register-source">

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

// With window.open()
window.open('...', '_blank', attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2})

Nesses casos, os dois URLs recebem solicitações navigation-source-eligible attributionsrc (solicitações que incluem o cabeçalho Attribution-Reporting-Eligible).

attributionsrc com ou sem um valor

Como abordado anteriormente, você pode especificar attributionsrc sem um URL. Também é possível especificar um único URL. Além disso, somente para origens (não aplicável a acionadores), 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 sinal de atividade separada, uma para cada URL, que inclui o cabeçalho da solicitação Attribution-Reporting-Eligible.

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

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

Para a primeira etapa de registro de visualizações, acesse as guias e selecione a etapa 1.

Para registrar uma fonte de atribuição para uma visualização, use uma tag de script ou imagem em que 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=..."/>

Também é possível especificar um valor de URL para attributionsrc da mesma forma que para cliques. Ou seja, para uma imagem ou um script, você pode definir o URL attributionsrc ou os URLs da seguinte maneira:

Com um único URL:

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

Com uma lista de URLs:

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

Como usar fetch() ou XMLHttpRequest()

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

// With fetch
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 });

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

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

Para a etapa 1 do registro de cliques, acesse as guias e selecione a etapa 1 de cliques.

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.

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

Ao receber a solicitação do navegador no servidor, responda e inclua na sua 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 aplicar 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.