Registrar acionadores de atribuição

Saiba como registrar acionadores de atribuição para contabilizar suas conversões.

Um acionador de atribuição é o evento que informa ao navegador para capturar conversões.

Siga as etapas neste documento para registrar acionadores para registrar conversões que o navegador atribui aos eventos de origem relevantes (ou seja, impressões ou cliques em anúncios).

Métodos de registro

Para registrar acionadores, use elementos HTML ou chamadas JavaScript:

• Tag <img>
• Tag <script>
• fetch chamada
• XMLHttpRequest

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

Registrar um acionador para atribuir uma conversão

O registro de um gatilho é semelhante a registrar um evento de fonte de atribuição. As etapas completas são descritas mais adiante. Aqui está o resumo:

1. Inicie o registro do acionador. Use um pixel ou uma chamada fetch() para fazer uma solicitação.

2. Conclua o registro do acionador respondendo com o acionador. cabeçalho de registro.

   Ao receber a solicitação de pixel, enviada ao endpoint definido no atributo src normal ou para o endpoint definido em attributionsrc, se escolher usar attributionsrc e atribuir um valor: responda com o cabeçalho Attribution-Reporting-Register-Trigger.

   Nesse cabeçalho, especifique os dados do gatilho que você quer exibir. e, no fim das contas, gerar relatórios. Qualquer resposta pode definir esse cabeçalho. Contanto que seja um resposta a uma solicitação feita por um site que corresponde a destination; serão correspondentes. Quando o cabeçalho é recebido, navegador procura origens correspondentes e programa um relatório.

   Exemplo para relatórios de eventos:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   

   Exemplo de relatórios de resumo:

   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   

.

Observação:quando o navegador recebe uma resposta do acionador de atribuição de um URL attributionsrc em uma determinada página, uma pesquisa de armazenamento local é feita para encontrar uma origem que corresponda ao site de origem e destino de attributionsrc a que essa página pertence. Se várias origens são encontradas, o navegador escolhe a que foi armazenada mais recentemente, a menos que elas tenham prioridades diferentes, em que o navegador vai escolher a que tiver a maior prioridade.

Como lidar com subdomínios

Se destination for https://advertiser.example, as conversões nas duas https://advertiser.example e seus subdomínios, como https://shop.advertiser.example, podem ser atribuídos.

Se destination for https://shop.advertiser.example, as conversões em https://advertiser.example e https://shop.advertiser.example podem ser atribuídos.

Atributos obrigatórios e opcionais

À medida que você usa elementos HTML ou faz chamadas JavaScript para registrar acionadores, 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	Gatilho
Tag <a>	N/A: as âncoras não podem registrar um acionador.
Tag <img>	attributionsrc é opcional. Cabeçalho é suficiente para registrar um gatilho.
Tag <script>	attributionsrc é opcional. Cabeçalho é suficiente para registrar um gatilho.
fetch chamada	A opção attributionReporting é obrigatório.
XMLHttpRequest	A opção attributionReporting é obrigatório.
window.open()	N/A:o window.open não pode registrar um acionador.

Etapa 1: iniciar o registro do acionador

É possível registrar um acionador usando um pixel (tag <img>) ou uma tag de script.

Usar um pixel de conversão novo ou existente

O exemplo a seguir aciona a atribuição em uma imagem existente adicionando o atributo attributionsrc.

A origem de attributionsrc precisa corresponder à origem que realizou o registro da fonte.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

O próximo exemplo aciona a atribuição adicionando um novo atributo attributionsrc de pixel de conversão.

A origem de src precisa corresponder à origem que realizou o registro da fonte.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Ponto-chave: Em ambos os casos, uma atribuição só pode ser acionada em uma página cujo site corresponda ao site fornecido no destino no registro da fonte.

Usando uma tag script

É possível registrar o acionador com uma tag de script. ele se comporta de maneira idêntica a <img>. Os exemplos de código a seguir ilustram o uso de fetch() e XMLHttpRequest() (XHR).

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

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

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

e

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

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

Ponto-chave:

• A origem ou o url definido em fetch() ou open() precisa corresponder à origem que realizou o registro da fonte.
• Uma atribuição só pode ser acionada em uma página cujo site corresponda ao site que foi fornecido no destino no registro da fonte.

attributionsrc com ou sem um valor

Você pode adicionar attributionsrc com ou sem um valor.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!-- With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

Se você definir um valor para attributionsrc, ele poderá ser um ou mais URLs separados por espaços.

O uso de um URL 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 do acionador respondendo a um separada da solicitação principal do elemento.

Por exemplo, se você precisar registrar acionadores em um elemento de imagem, talvez você não controle a resposta da imagem. Nesse caso, convém uma configuração em que você envia o cabeçalho de registro de acionador como resposta a uma solicitação separado da imagem 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.

Etapa 2: responder com um cabeçalho

Ao receber a solicitação do navegador, responda e inclua na sua resposta o cabeçalho Attribution-Reporting-Register-Trigger:

JSON.stringify({
  event_trigger_data: [{
    trigger_data: "412444888111012",
    // Optional
    priority: "1000000000000",
    deduplication_key: "2345698765"
  }],
  debug_key: "1115698977"
});

Cuidado:o valor do campo event_trigger_data precisa estar aninhado entre colchetes, porque o navegador espera uma matriz JSON. Isso é útil para filtros.

Próximas etapas

Saiba como registrar fontes de atribuição.