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 instrui o navegador a 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 no anúncio.

Métodos de registro

Para registrar acionadores, 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 acionador.

Registrar um acionador para atribuir uma conversão

Registrar um acionador é semelhante ao registrar um evento de fonte de atribuição. As etapas completas são descritas posteriormente. 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 cabeçalho de registro do acionador.
   
   

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

   Nesse cabeçalho, especifique os dados do acionador que você quer exibir nos relatórios. Qualquer resposta pode definir esse cabeçalho. As origens serão correspondidas desde que seja uma resposta a uma solicitação feita a partir de um site que corresponda a destination. Quando o cabeçalho é recebido, o navegador procura origens correspondentes e programa um relatório.

   Exemplo de relatórios de eventos:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // 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 de acionador de atribuição do URL Attributionsrc em uma determinada página, uma pesquisa de armazenamento local é feita para encontrar uma fonte que corresponda à origem de Attributionsrc e ao eTLD+1 desse URL da página. <br> Se várias fontes forem encontradas, o navegador vai escolher a que foi armazenada mais recentemente, a menos que as fontes tenham prioridades diferentes. Nesse caso, o navegador vai escolher a que tiver a maior prioridade.

Como lidar com subdomínios

Se destination for https://advertiser.example, as conversões em https://advertiser.example e nos subdomínios dela, 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 acionadores, 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	Gatilho
Tag <a>	N/A As âncoras não registram um acionador.
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 ligação	A opção attributionReporting é obrigatória.
XMLHttpRequest	A opção attributionReporting é obrigatória.
window.open()	N/A window.open não pode registrar um acionador.

Etapa 1: iniciar o registro do acionador

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

Como usar um pixel de conversão novo ou existente

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

Importante: * a origem de src precisa corresponder à origem que executou o registro dela. * Uma atribuição só pode ser acionada em uma página com um eTLD+1 correspondente ao site informado no destino após o registro da fonte.

Como usar uma tag script

É possível executar o registro do acionador com uma tag de script. Ela 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 com eficácia o que uma solicitação HTML com attributionsrc faria:

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

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

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

Ponto-chave:a origem de <code>src</code> precisa corresponder à origem que executou o registro da fonte. - Uma atribuição só pode ser acionada em uma página em que <a href="https://web.dev/same-site-same-origin/#%22schemeful-same-site%22">eTLD+1</a> corresponda ao site fornecido em <code>destino</code> após o registro da origem.

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 precisará ser um único URL.

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 o cabeçalho de 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.

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 ser aninhado entre colchetes, porque o navegador espera uma matriz JSON. Isso é útil para filtros.

Próximas etapas

Saiba como registrar fontes de atribuição.