Registrar acionadores de atribuição

Saiba como registrar gatilhos de atribuição para contar suas conversões.

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

Seguindo as etapas deste documento, você pode registrar acionadores para registrar conversões que o navegador atribui aos eventos de origem relevantes, ou seja, impressões ou cliques de 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 gatilho.

Registrar um acionador para atribuir uma conversão

O registro de um acionador é semelhante ao registro de um evento de fonte de atribuição. As etapas completas são descritas mais adiante. Confira o resumo:

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

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

    Ao receber a solicitação de pixel, enviada ao endpoint definido no atributo src usual ou ao endpoint definido em attributionsrc se você tiver escolhido usar attributionsrc e atribuído a ele um valor, responda com o cabeçalho Attribution-Reporting-Register-Trigger.

    Nesse cabeçalho, especifique os dados de acionamento que você quer que apareçam nos relatórios. Qualquer resposta pode definir esse cabeçalho. Desde que seja uma resposta a uma solicitação feita em um site que corresponda ao destination, as fontes serão correspondidas. Quando o cabeçalho é recebido, o navegador procura fontes correspondentes e programa um relatório.

    Exemplo de relatórios no nível do evento:

    {
  "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 em https://advertiser.example e nos subdomínios dele, como https://shop.advertiser.example, poderão ser atribuídas.

Se destination for https://shop.advertiser.example, as conversões em https://advertiser.example e https://shop.advertiser.example poderão ser atribuídas.

Atributos obrigatórios e opcionais

Ao usar elementos HTML ou fazer chamadas JavaScript para registrar gatilhos, talvez seja necessário usar attributionsrc ou attributionReporting. Consulte a tabela a seguir para saber quando eles são obrigatórios.

Quando attributionsrc é opcional, o uso dele indica que a solicitação está qualificada para os relatórios de atribuição. Se você usar attributionsrc, o navegador enviará o cabeçalho Attribution-Reporting-Eligible. Também é útil para a medição de app para Web: 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 gatilho.
Tag <img> attributionsrc é opcional. O cabeçalho é suficiente para registrar um acionador.
Tag <script> attributionsrc é opcional. O cabeçalho é suficiente para registrar um acionador.
fetch chamada A opção attributionReporting é obrigatória.
XMLHttpRequest A opção attributionReporting é obrigatória.
window.open() N/A:window.open não pode registrar um gatilho.

Etapa 1: iniciar o registro do gatilho

Você pode registrar um acionador usando um pixel (tag <img>) ou uma tag de script.

Usar um pixel de conversão novo ou atual

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

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

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

O exemplo a seguir aciona a atribuição adicionando um novo atributo attributionsrc do pixel de conversão.

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

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

Usar uma tag de script

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

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

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

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

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

É possível 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 manutenção de atividade separada, uma para cada URL, que inclui o cabeçalho de solicitação Attribution-Reporting-Eligible.

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

Por exemplo, se você precisar registrar gatilhos em um elemento de imagem, talvez não tenha controle sobre a resposta da imagem. Nesse caso, você vai querer uma configuração em que envie o cabeçalho de registro do gatilho como uma resposta a uma solicitação separada da imagem e que possa controlar completamente. Ao especificar um valor explícito para attributionsrc, você está instruindo o navegador a fazer essa solicitação extra e configurando o destino dela.

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.