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
ligaçãoXMLHttpRequest
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 acionador é semelhante ao registro de um evento de fonte de atribuição. As etapas completas são descritas mais adiante. Aqui está o resumo:
- Inicie o registro do acionador. Use um pixel ou uma chamada
fetch()
para fazer uma solicitação. Conclua o registro do acionador respondendo com o cabeçalho de registro do acionador.
Ao receber a solicitação de pixel, enviada para o endpoint definido no atributo
src
normal ou para o endpoint definido emattributionsrc
, se você escolheu usarattributionsrc
e receber um valor, responda com o cabeçalhoAttribution-Reporting-Register-Trigger
.Nesse cabeçalho, especifique os dados do acionador que você quer que apareçam nos relatórios. Qualquer resposta pode definir esse cabeçalho. Contanto que seja uma resposta a uma solicitação feita a partir de um site que corresponda a
destination
, as origens serão correspondidas. Quando o cabeçalho é recebido, o 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 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 acionadores, talvez
seja necessário usar attributionsrc
ou attributionReporting
. Consulte a tabela a seguir para saber quando eles são
necessá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 enviará o
cabeçalho Attribution-Reporting-Eligible
. Também é útil para 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 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: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. 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 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 });
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 o cabeçalho de solicitação Attribution-Reporting-Eligible
.
Isso é útil se você quer fazer o registro do acionador respondendo a uma solicitação separada da solicitação principal do elemento.
Por exemplo, se for necessário registrar acionadores em um elemento de imagem,
talvez você não esteja no controle da resposta da imagem. Nesse caso,
convém enviar o cabeçalho de registro de acionador como uma resposta a uma solicitação
separada da imagem e que você pode controlar totalmente. Ao
especificar um valor explícito para attributionsrc
, você instrui o
navegador a fazer essa solicitação extra e configura 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"
});
Próximas etapas
Saiba como registrar fontes de atribuição.