Filtrar origens antes da atribuição usando os escopos de atribuição

Os escopos de atribuição permitem que os chamadores de API especifiquem uma lista de strings durante o registro de fonte e acionador que pode ser usada para filtragem antes da atribuição. Isso permite uma filtragem mais refinada para aumentar a eficiência da API e oferecer mais flexibilidade. Por exemplo, ele permite rastrear anunciantes separados no mesmo site de maneira distinta. Também facilita o rastreamento de várias campanhas ou produtos em um único banner de anúncio.

Os escopos de atribuição são campos opcionais que podem ser definidos durante o registro de fonte e acionador. Durante a atribuição, apenas as fontes cujos valores de escopo de atribuição contêm pelo menos um dos valores de escopo de atribuição do gatilho serão consideradas para atribuição. Se nenhum escopo for especificado no gatilho, todas as fontes serão consideradas. Antes de continuar, familiarize-se com a API Attribution Reporting e os filtros de alto nível.

Durante o registro da fonte

Um parâmetro opcional attribution_scopes é adicionado ao cabeçalho Attribution-Reporting-Register-Source, que contém dois parâmetros obrigatórios: values e limit, e um parâmetro opcional: max_event_states.

  • limit:representa o número total de escopos distintos permitidos por destino para a origem de relatórios da fonte. Todas as fontes registradas com a mesma origem e destino de relatório, mas um limite menor, serão excluídas.
  • values:representa a lista de escopos de atribuição para uma determinada origem. Esses valores precisam ser strings com um tamanho máximo de 50.
  • max_event_states (opcional): representa o número máximo de estados de evento que um caller da API planeja usar em todos os registros subsequentes de origem de evento. As fontes registradas com a mesma origem e destino de relatórios, mas um max_event_states value diferente, serão excluídas. O valor padrão desse campo opcional é 3.

Exemplo de registro da fonte

  Attribution-Reporting-Register-source: {
  //optional
  "attribution_scopes":{
  "limit": <int>,
  "values": <list of strings>,
  // optional
  "max_event_states": <int>
    },
  ...
  }

Durante o registro do acionador

Um parâmetro opcional attribution_scopes é adicionado ao cabeçalho Attribution-Reporting-Register-Trigger durante o registro do acionador. Verifique se o valor do parâmetro é uma lista de strings que representam os escopos do acionador. O acionador só vai corresponder a fontes cujo parâmetro attribution_scopes contenha pelo menos um dos attribution_scopes do acionador, se especificado.

Exemplo de registro de acionador

Attribution-Reporting-Register-Trigger: {
//optional
"attribution_scopes": <list of strings>,
...
}

Exemplo de escopos de atribuição

O exemplo a seguir mostra o caso em que um gatilho é atribuído a uma origem ao usar escopos de atribuição.

Registro da fonte nº 1

  Attribution-Reporting-Register-source: {
  "destination": "https://trigger.example",
  "attribution_scopes": {
  "limit": 2,
  "values": ["advertiser1"],
  "max_event_states": 3
  },
  ...
  }

Registro da fonte nº 2

  Attribution-Reporting-Register-source: {
  "destination": "https://trigger.example",
  "attribution_scopes": {
  "limit": 2,
  "values": ["advertiser2"],
  "max_event_states": 3
  },
  ...
  }

Registro do acionador

  Attribution-Reporting-Register-Trigger: {
  "attribution_scopes": ["advertiser1"],
  ...
  }

Quando o registro do acionador ocorre, a API seleciona as fontes a serem consideradas para atribuição que têm valores de "attribution_scopes" que se cruzam com os valores no registro do acionador. Os registros de origem correspondentes vão continuar com o restante do fluxo de atribuição. Neste exemplo, o autor da chamada da API vai receber um relatório de atribuição que atribui o registro do acionador ao primeiro registro de origem.

Escopos de atribuição x filtros

Embora a funcionalidade dos escopos e filtros de atribuição possa parecer semelhante, o fator distintivo é onde eles são aplicados no fluxo de registro do gatilho. A filtragem de escopos de atribuição acontece antes da atribuição. Isso significa que ele reduz o pool de fontes candidatas não expiradas que têm o mesmo site de destino e origem de relatório, com base em quais fontes têm escopos que se cruzam com os escopos encontrados no gatilho. No entanto, os filtros de nível superior são aplicados depois que um gatilho é atribuído a uma única origem. Se os filtros de origem e de acionador não se cruzarem, nenhum relatório será gerado.

A imagem a seguir mostra um grupo de origens e um acionador que têm o mesmo site de destino e origem de relatórios e não estão expirados. Vamos falar brevemente sobre como os escopos e filtros de atribuição são usados e se um relatório será gerado com base nas fontes e acionadores disponíveis.

Quatro caixas rotuladas com os números de origem de 1 a 4 e uma única caixa rotulada como &quot;Gatilho nº 1&quot;. A primeira origem tem os seguintes atributos &quot;Escopo da atribuição&quot;: &quot;activewear&quot; e Prioridade: 2. A segunda origem tem os atributos &quot;Escopo da atribuição&quot;: &quot;roupas esportivas&quot; e Filtro: &quot;roupas de frio&quot;. A terceira fonte tem os atributos &quot;Escopo da atribuição&quot;: &quot;casualwear&quot;, Filtro: &quot;outerwear&quot;. A quarta fonte tem os atributos &quot;Escopo de atribuição&quot;: &quot;casualwear&quot; e Filtro: &quot;outerwear&quot; e Prioridade: 1. O gatilho tem os atributos &quot;Escopo da atribuição&quot;: &quot;casualwear&quot; e Filtro: &quot;outerwear&quot;.
Exemplo de como a atribuição funciona com escopos e filtros

Antes da atribuição

  • A origem nº 1 é filtrada porque o escopo de atribuição dela não corresponde ao escopo de casualwear do acionador. Ter a maior prioridade entre todas as fontes disponíveis não impede que ela seja filtrada, já que a filtragem pré-atribuição ocorre antes da verificação das prioridades.
  • A origem nº 2 também é filtrada por não ter o mesmo escopo do acionador. Essa origem também tem o mesmo filtro que o acionador, mas os filtros de alto nível não são aplicados até depois da atribuição.

Durante a atribuição

  • A origem nº 3 não é selecionada para atribuição porque tem menor prioridade que a origem nº 4.
  • A origem nº 4 é selecionada porque tem um escopo de atribuição correspondente ao acionador e a maior prioridade. Os filtros de alto nível são aplicados após a atribuição, portanto, não são considerados durante o processo.

Atribuição de postagem

  • Nenhum relatório é gerado porque os filtros de alto nível para a origem selecionada (origem nº 4) e o acionador não se cruzam.

O exemplo anterior não resulta na geração de um relatório. No entanto, se a quarta fonte for removida completamente:

As mesmas quatro caixas rotuladas como números de origem de 1 a 4 e uma única caixa rotulada como &quot;Acionador nº 1&quot;. A diferença nesta imagem é que a caixa marcada como &quot;Fonte nº 4&quot; está riscada com um X vermelho.
Exemplo modificado de como a atribuição funciona com escopos e filtros

Durante a atribuição

  • A fonte 3 é selecionada porque tem um escopo de atribuição que se cruza com o acionador.

Atribuição de postagem

  • A fonte nº 3 não é rejeitada porque o filtro dela se cruza com o filtro no gatilho. Em seguida, a atribuição passará pelo restante das verificações de atribuição de postagem, terminando com a geração de um relatório se passar em todas as verificações.

Os escopos de atribuição reduzem o número de fontes consideradas para atribuição. As etapas de atribuição restantes são aplicadas a esse conjunto menor de fontes, o que pode resultar em um relatório.

Posição dos escopos de atribuição no fluxo de atribuição

Os escopos de atribuição são aplicados antes que uma origem seja selecionada para atribuição. Isso também precede os filtros de nível superior e a filtragem personalizada da janela de relatório. O diagrama a seguir mostra uma versão simplificada do fluxo geral de atribuição com o escopo de atribuição ocorrendo antes da atribuição e do restante das verificações de atribuição.

Uma versão simplificada do fluxo de atribuição com cada etapa representada como um quadrado vinculado à próxima etapa por uma seta. As etapas em ordem são &quot;Registro de origem&quot;, &quot;Registro de acionador&quot;, &quot;Correspondência de origem&quot;, &quot;Verificação de escopos de atribuição&quot;, &quot;Atribuição&quot;, &quot;Verificação de filtros&quot;, &quot;Desativação de outras origens&quot;, &quot;Verificações de atribuição&quot; e &quot;Geração de relatórios&quot;.
Fluxo de atribuição simplificado

Operações de fluxo de atribuição

Confira a seguir um resumo das várias operações realizadas durante o fluxo de atribuição:

  • Registro de origem:quando um usuário interage com um anúncio no site do anunciante, um evento de origem é registrado. Em seguida, o dispositivo envia uma solicitação ao endpoint da origem de relatórios, que responde com um cabeçalho que contém dados de eventos de origem.
  • Registro do acionador:quando uma conversão ocorre no site do anunciante, um evento acionador é registrado. Outra solicitação é enviada pelo dispositivo à origem de relatórios, que responde com um cabeçalho que contém dados de eventos de acionamento.
  • Correspondência de origem:o dispositivo corresponde a eventos de origem e de acionamento com base em critérios como site de destino, origem do relatório e expiração.
  • Verificação de escopos de atribuição:as fontes são filtradas com base na interseção entre os valores de atribuição_scopes da fonte e do acionador.
  • Atribuição:o dispositivo seleciona a fonte de maior prioridade para atribuição se várias fontes corresponderem. Se as prioridades forem iguais, a mais recente será selecionada.
  • Verificação de filtros:o dispositivo compara os filtros de origem e de acionador para determinar se eles correspondem. Se os filtros não corresponderem, a atribuição será descartada.
  • Desativação de outras fontes:se os filtros da fonte escolhida forem correspondentes, o dispositivo desativará as fontes correspondentes durante a etapa de correspondência de fontes. As fontes desativadas incluem aquelas em que os escopos de atribuição não correspondem aos escopos de acionamento.
  • Verificações pós-atribuição:o dispositivo realiza mais verificações na atribuição selecionada, como verificar se a origem está com ruído de relatórios falsos, se há atribuições duplicadas usando chaves de remoção de duplicação, se o acionador está dentro do período de relatório da origem e se há limites de taxa.
  • Geração de relatórios:se todas as verificações forem aprovadas, o dispositivo vai gerar e programar um relatório de atribuição para ser enviado ao endpoint da origem de relatórios.

Próximas etapas