IDs de relatórios

Saiba como os IDs de relatórios funcionam em um leilão com Protected Audience

Visão geral

Os IDs de relatórios são identificadores associados a um anúncio que estão disponíveis para uso na geração e pontuação de lances e na geração de relatórios. Os IDs de relatório são fornecidos pelo comprador na configuração do grupo de interesse e ficam disponíveis no generateBid(), scoreAd(), reportResult() e reportWin() em várias condições discutidas neste guia.

Os IDs de relatórios permitem que você informe um identificador para um anúncio, além de ativar casos de uso como transações.

Disponibilidade de IDs de relatórios

Há três tipos de IDs de relatórios:

• IDs de relatórios não selecionáveis
  • buyerReportingId (uma string)
  • buyerAndSellerReportingId (uma string)
• IDs de relatórios selecionáveis
  • selectableBuyerAndSellerReportingIds (uma matriz de strings)

Os IDs de relatórios se comportam de maneira diferente dependendo do uso dos IDs de relatórios selecionáveis. Quando apenas IDs de relatórios não selecionáveis são usados, eles ficam disponíveis somente nas funções de relatórios. Quando IDs de relatórios selecionáveis são usados, com IDs de relatórios não selecionáveis, se necessário, todos os IDs definidos ficam disponíveis também em generateBid() e scoreAd().

Importante :os IDs de relatórios são verificados em relação ao k-anonimato antes de ficarem disponíveis nas funções de relatórios (reportResult() e reportWin()).

IDs de relatórios não selecionáveis

Disponibilidade dos IDs de relatórios selecionáveis

buyerReportingId e buyerAndSellerReportingId são IDs de relatórios não selecionáveis definidos na configuração do grupo de interesse que ficam disponíveis nas funções de relatórios de compradores e vendedores. As funções de relatórios do comprador e do vendedor só serão executadas para o anúncio vencedor, e as funções receberão os IDs de relatório definidos para esse anúncio vencedor.

Quando usada sem IDs de relatórios selecionáveis, a função de relatórios do comprador recebe buyerReportingId ou buyerAndSellerReportingId, dependendo do comportamento de substituição, e a função de relatórios do vendedor recebe buyerAndSellerReportingId. Se buyerReportingId e buyerAndSellerReportingId não forem definidos na configuração do grupo de interesse, a função reportWin() receberá o nome do grupo de interesse (interestGroupName) do lance vencedor.

Os IDs não selecionáveis não vão estar disponíveis em generateBid() e scoreAd() se não forem usados com IDs de relatórios selecionáveis.

IDs de relatórios em grupos de interesse

Os IDs de relatórios são definidos pelo comprador para cada anúncio em um grupo de interesse:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Relatórios do vendedor

Durante a fase de geração de relatórios do vendedor, o valor buyerAndSellerReportingId fica disponível para reportResult():

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Antes que o ID seja disponibilizado em reportResult(), ele é verificado em relação ao k-anonimato com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio não será incluído na verificação até o primeiro trimestre de 2025. Se não for k-anônimo, a função reportResult() ainda será executada, mas o valor do ID de relatório não estará disponível dentro da função.

Relatórios de compradores

Durante a fase de geração de relatórios do comprador do leilão, um ID de relatório fica disponível para o reportWin(). Se mais de um ID de relatório for definido no grupo de interesse, uma regra de substituição será aplicada onde buyerAndSellerReportingId substituir buyerReportingId:

• Se buyerAndSellerReportingId e buyerReportingId estiverem definidos, buyerAndSellerReportingId vai substituir buyerReportingId, e buyerAndSellerReportingId vai ficar disponível dentro de reportWin().
• Se apenas buyerReportingId for definido, buyerReportingId vai ficar disponível.
• Se nem buyerAndSellerReportingId nem buyerReportingId forem definidos, interestGroupName estará disponível.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

O ID de relatório disponibilizado em reportWin() é verificado em busca de k-anonimato com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio não será incluído na verificação até o primeiro trimestre de 2025. Se ela for reprovada na verificação de k-anonimato, reportWin() ainda será executado, mas o valor do ID de relatório não vai ficar disponível na função.

Somente buyerReportingId está definido

Se apenas buyerReportingId for definido na configuração do grupo de interesse:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

Em seguida, buyerReportingId está disponível dentro de reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

Antes de ficar disponível para reportWin(), o buyerReportingId é verificado em busca de k-anonimato com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio não será incluído na verificação até o primeiro trimestre de 2025.

Somente compradorAndSellerReportingId é definido

Se apenas buyerAndSellerReportingId for definido na configuração do grupo de interesse:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Em seguida, buyerAndSellerReportingId está disponível dentro de reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Antes de ficar disponível para reportWin(), a buyerAndSellerReportingId é verificada quanto à k-anonimização com o proprietário do grupo de interesses, o URL do script de lance, o URL de renderização e o tamanho do anúncio (o tamanho do anúncio é excluído dessa verificação até pelo menos o 1º trimestre de 2025).

Tanto buyerAndSellerReportingId quanto buyerReportingId estão definidos

Se buyerAndSellerReportingId e buyerReportingId estiverem definidos na configuração do grupo de interesse:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Então apenas buyerAndSellerReportingId estará disponível dentro de reportWin() devido ao comportamento de substituição:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Antes de ficar disponível para reportWin(), o buyerAndSellerReportingId é verificado em busca de k-anonimato com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio não será incluído na verificação até o primeiro trimestre de 2025.

Nem buyerAndSellerReportingId nem buyerReportingId estão definidos

Se nenhum dos IDs de relatórios for definido na configuração do grupo de interesse:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

O grupo de interesse name estará disponível em reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

Antes de ser disponibilizado para reportWin(), o nome do grupo de interesse (interestGroupName) é verificado em relação ao k-anonimato com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio não será incluído nessa verificação até, no mínimo, o primeiro trimestre de 2025.

IDs de relatórios selecionáveis

Disponibilidade dos IDs de relatórios com IDs de relatórios selecionáveis

Os IDs de relatórios selecionáveis permitem que um comprador selecione um ID durante a geração do lance, e o navegador disponibiliza o valor selecionado para as funções de relatório e scoreAd(). O valor selectableBuyerAndSellerReportingIds, que é uma matriz de strings, é fornecido para generateBid(), e o comprador pode retornar um ID selecionado como selectedBuyerAndSellerReportingId.

As funções generateBid() e scoreAd() serão executadas para cada anúncio definido na configuração do grupo de interesse e receberão os IDs de relatório para cada anúncio. As funções de relatórios do comprador e do vendedor só serão executadas para o anúncio vencedor, e as funções receberão os IDs de relatório definidos para esse anúncio vencedor.

Quando IDs de relatórios não selecionáveis são usados em conjunto com IDs de relatórios selecionáveis, o comportamento deles muda em relação ao fluxo de trabalho descrito na seção anterior. Ao contrário do comportamento inicial dos IDs de relatórios não selecionáveis estarem disponíveis apenas dentro das funções de relatórios, os IDs de relatórios selecionáveis permitem que IDs de relatórios não selecionáveis sejam disponibilizados também dentro do generateBid() e do scoreAd().

Observação: os IDs de relatórios selecionáveis vão estar disponíveis no Stable na versão M130. Antes que os IDs de relatórios selecionáveis cheguem à versão estável, eles podem ser testados com a inicialização do Canary M130 na linha de comando com as flags --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport.

Grupo de interesse

O campo de IDs de relatórios selecionável (selectableBuyerAndSellerReportingIds) é uma matriz de strings definidas pelo comprador no grupo de interesse de um anúncio. Os IDs de relatórios não selecionáveis também podem ser definidos com os IDs de relatórios selecionáveis:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Geração de lance do comprador

Se selectableBuyerAndSellerReportingIds tiver sido definido na configuração do grupo de interesse, ele ficará disponível dentro de generateBid() com outros IDs de relatórios definidos.

function generateBid(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  } = browserSignals;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

O comprador pode escolher um dos IDs da matriz selectableBuyerAndSellerReportingIds em generateBid() e retornar o ID selecionado como selectedBuyerAndSellerReportingId. O lance é rejeitado se o valor selecionado não estiver na matriz selectableBuyerAndSellerReportingIds. Se selectableBuyerAndSellerReportingIds for definido na configuração do grupo de interesse e o comprador não retornar selectedBuyerAndSellerReportingId de generateBid(), os IDs de relatórios serão revertidos para o comportamento descrito para IDs de relatórios não selecionáveis.

Um lance com um valor retornado para selectedbuyerAndSellerReportingId só poderá vencer o leilão se o valor de selectedbuyerAndSellerReportingId for conjuntamente k-anônimo com buyerAndSellerReportingId (se houver), buyerReportingId (se houver), o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio. O tamanho do anúncio será excluído dessa verificação até pelo menos o primeiro trimestre de 2025.

Observação: nos casos em que generateBid() é executado novamente porque a invocação inicial não produziu lances com anúncios que passaram nas verificações de k-anonimato, os selectableBuyerAndSellerReportingIds que não passarem na verificação de k-anonimato não vão estar presentes no grupo de interesse na nova execução.

Pontuação de anúncios do vendedor

Para o vendedor, o selectedBuyerAndSellerReportingId retornado pelo comprador de generateBid() fica disponível no scoreAd(), com buyerAndSellerReportingId se tiver sido definido na configuração do grupo de interesse.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Relatórios do vendedor

Para os relatórios do vendedor, o selectedBuyerAndSellerReportingId retornado pelo comprador de generateBid() fica disponível no reportResult(), com buyerAndSellerReportingId, se tiver sido definido no grupo de interesse.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

Se selectableBuyerAndSellerReportingIds tiver sido definido na configuração do grupo de interesse e selectedBuyerAndSellerReportingId for retornado de generateBid(), ele não poderá vencer o leilão, a menos que selectedBuyerAndSellerReportingId e buyerAndSellerReportingId (se presentes) forem k-anônimos com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio (o tamanho do anúncio será excluído dessa verificação até pelo menos o primeiro trimestre de 2025), e reportResult() não será executado para esse lance. Portanto, se reportResult() for chamado com um valor de selectedBuyerAndSellerReportingId, isso significa que os IDs de relatórios foram aprovados na verificação de k-anonimato, e todos os IDs de relatórios definidos estarão disponíveis em reportResult().

Relatórios de compradores

Se selectableBuyerAndSellerReportingIds tiver sido definido na configuração do grupo de interesse e selectedBuyerAndSellerReportingId tiver sido retornado de generateBid(), todos os IDs de relatórios definidos na configuração do grupo de interesse ficarão disponíveis. Assim como nos relatórios do vendedor, se os IDs de relatório não forem k-anônimos, eles não vão poder vencer o leilão, e a reportWin() não vai ser executada para esse lance.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Substituir regras

Aqui resumimos as regras de substituição dos IDs de relatórios não selecionáveis e dos IDs de relatórios selecionáveis. Os valores de selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId e o nome do grupo de interesse transmitidos para reportWin() são determinados pelo navegador com a seguinte lógica:

• Se selectedBuyerAndSellerReportingId for retornado de um lance, selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (se definido no grupo de interesse) e buyerReportingId (se definido no grupo de interesse) vão estar disponíveis para geração de relatórios.
• Caso contrário, se buyerAndSellerReportingId for definido no grupo de interesse, somente buyerAndSellerReportingId estará disponível para geração de relatórios.
• Caso contrário, se buyerReportingId estiver definido no grupo de interesse, apenas buyerReportingId estará disponível para geração de relatórios.
• Caso contrário, apenas o grupo de interesse name vai ficar disponível para relatórios.

A tabela a seguir descreve o comportamento de substituição:

Os IDs de relatórios são definidos na configuração do grupo de interesse?			IDs de relatórios disponíveis
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Sim, e selecionei em generateBid()	Opcional	Opcional	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definido) 3) buyerReportingId (se definido)	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definido)
Não ou não selecionado em generateBid()	Sim	Ignorado	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Não ou não selecionado em generateBid()	Não	Sim	buyerReportingId	Nenhum
Não ou não selecionado em generateBid()	Não	Não	interestGroupName	Nenhum

Engajamento e compartilhamento de feedback

• Para saber mais sobre os IDs de relatórios, consulte a seção "ID de relatórios" na explicação da API Protected Audience.
• GitHub: faça perguntas e acompanhe a discussão em problemas no repositório da API.
• W3C: discuta casos de uso do setor na chamada da WICG.
• Avisos: participar ou visualizar a lista de e-mails.
• Suporte ao desenvolvedor do Sandbox de privacidade: faça perguntas e participe de discussões no repositório de suporte ao desenvolvedor do Sandbox de privacidade.
• Chromium: registre um bug do Chromium para fazer perguntas sobre a implementação disponível para teste.