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
  }
}
.

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>

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();

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"
});

Próximas etapas

Saiba como registrar fontes de atribuição.