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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Os escopos de atribuição permitem que os autores de chamada da API especifiquem uma lista de strings durante o registro de origem e acionador que pode ser usada para filtrar antes da atribuição. Isso permite que a filtragem de grãos mais finos aumente a eficiência da API e ofereça mais flexibilidade. Por exemplo, ele permite rastrear anunciantes diferentes no mesmo site de forma distinta. Também facilita o acompanhamento 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 origem e acionador. Durante a atribuição, apenas as origens cujos valores de escopo de atribuição contêm pelo menos um dos valores de escopo de atribuição do acionador serão consideradas. Se nenhum escopo for especificado no acionador, todas as fontes serão consideradas. Antes de continuar, você precisa conhecer 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: valores e limite e um parâmetro opcional: max_event_states.

• limite:representa o número total de escopos distintos permitidos por destino para a origem de relatórios de origem. Todas as origens registradas com a mesma origem e destino de relatórios, mas com um limite menor, serão excluídas.
• values:representa a lista de escopos de atribuição de uma determinada origem. Esses valores precisam ser strings com um comprimento máximo de 50.
• max_event_states (opcional): representa o número máximo de estados de evento que um autor da chamada de API planeja usar em todos os registros de origem de evento subsequentes. Todas as origens 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 para esse 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 às origens cujo parâmetro de valores de attribution_scopes contém pelo menos um dos attribution_scopes do acionador, se especificado.

Exemplo de registro do 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 acionador é atribuído a uma origem ao usar escopos de atribuição.

Registro da origem 1

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

Registro da fonte 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 que serão consideradas para atribuição e 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.

Atribuições e filtros

Embora a funcionalidade dos escopos e filtros de atribuição pareça semelhante, o fator de diferenciação é onde eles são aplicados no fluxo de registro do acionador. A filtragem dos escopos de atribuição acontece antes da atribuição. Isso significa que o conjunto de origens candidatas não expiradas com o mesmo site de destino e origem de relatórios é reduzido com base nas origens que têm escopos que se cruzam com os escopos encontrados no acionador. No entanto, os filtros de nível superior são aplicados depois que um acionador é atribuído a uma única origem. Se os filtros de origem e 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 a mesma origem de denúncia 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 nos acionadores disponíveis.

<img "activewear"="" "attribution="" "casualwear"="" "casualwear",="" "outerwear"="" "outerwear".="" "outerwear"."="" #1".the="" 1.="" 2.="" alt="An image showing 4 boxes labelled sources numbered 1 through 4 and a single box labelled " and="" attributes="" filter:="" first="" following="" fourth="" has="" priority:="" scope":="" second="" source="" src="/static/assets/images/attribution-scopes-example-1.png" the="" third="" title="Example on how attribution works with attribution scopes and filters" trigger="" />

Antes da atribuição

• A origem 1 é filtrada porque o escopo de atribuição dela não corresponde ao escopo do acionador de casualwear. Ter a maior prioridade entre todas as origens 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 2 também é filtrada por não ter o mesmo escopo do acionador. Essa fonte também tem o mesmo filtro do acionador, mas os filtros de alto nível só são aplicados após a atribuição.

Durante a atribuição

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

Atribuição pós-instalação

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

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

Durante a atribuição

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

Atribuição pós-instalação

• A fonte 3 não é rejeitada porque o filtro dela se cruza com o filtro no acionador. A atribuição vai passar pelo restante das verificações pós-atribuição e, se passar em todas, vai gerar um relatório.

Os escopos de atribuição reduzem o número de origens consideradas para atribuição. As etapas restantes de atribuição são aplicadas a esse conjunto menor de origens, 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órios. 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.

<img "attribution="" "attribution",="" "deactivation="" "filters="" "report="" "source="" "trigger="" alt="Uma imagem mostrando 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 na ordem são " and="" check",="" checks"="" generation"."="" matching",="" of="" other="" registration",="" scopes="" source="" sources",="" src="/static/assets/images/attribution-scopes-attribution-flow.png" title="Simplified attribution flow diagram" />

Operações do 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 para o endpoint da origem de relatórios, que responde com um cabeçalho contendo 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 para a origem de relatórios, que responde com um cabeçalho contendo dados do evento de acionamento.
• Correspondência de origem:o dispositivo corresponde a eventos de origem e acionador com base em critérios como site de destino, origem do relatório e validade.
• Verificação dos escopos de atribuição:as fontes são filtradas com base na interseção entre os valores de attribution_scopes da fonte e do acionador.
• Atribuição:o dispositivo seleciona a fonte de atribuição de maior prioridade 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 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 corresponderem, o dispositivo vai desativar as fontes correspondentes durante a etapa de correspondência de origem. As fontes desativadas incluem fontes cujos escopos de atribuição não correspondem aos escopos do acionador.
• Verificações pós-atribuição:o dispositivo realiza mais verificações na atribuição selecionada, como verificar se a origem tem relatórios falsos, verificar atribuições duplicadas usando chaves de eliminação de duplicação, verificar se o acionador está dentro da janela de relatório da origem e verificar os limites de taxa.
• Geração de relatórios:se todas as verificações forem bem-sucedidas, o dispositivo vai gerar e programar um relatório de atribuição para ser enviado ao endpoint da origem do relatório.

Próximas etapas

• Leia mais sobre os escopos de atribuição no GitHub explainer sobre a filtragem antes da atribuição.
• Leia mais sobre os filtros em Definir regras de clientes usando filtros.