IDs de relatórios

Saiba como os IDs de relatórios funcionam em um leilão da API 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 de lances, na pontuação de lances e na geração de relatórios. Os IDs de relatórios são fornecidos pelo comprador na configuração do grupo de interesse e ficam disponíveis em generateBid(), scoreAd(), reportResult() e reportWin() em várias condições, conforme discutido neste guia.

Com os IDs de relatórios, você pode informar um identificador de um anúncio e também permitir casos de uso como contratos.

Disponibilidade de IDs de relatórios

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

• 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 se os IDs de relatórios selecionáveis são usados. Quando apenas IDs de relatórios não selecionáveis são usados, eles ficam disponíveis apenas 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 também ficam disponíveis em generateBid() e scoreAd().

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

IDs de relatórios não selecionáveis

Disponibilidade de 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 do comprador e do vendedor. As funções de relatório do comprador e do vendedor só serão executadas para o anúncio vencedor e vão receber os IDs de relatório definidos para esse anúncio.

Quando usado 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 nem buyerReportingId nem buyerAndSellerReportingId estiverem definidos na configuração do grupo de interesse, a função reportWin() vai receber o nome do grupo de interesse (interestGroupName) do lance vencedor.

Os IDs não selecionáveis não estão 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 de buyerAndSellerReportingId fica disponível para reportResult():

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

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

Antes que o ID fique disponível no reportResult(), ele é verificado para 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 é excluído dessa verificação até pelo menos 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 do comprador

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

• Se buyerAndSellerReportingId e buyerReportingId estiverem definidos, buyerAndSellerReportingId vai substituir buyerReportingId, e buyerAndSellerReportingId vai estar disponível em reportWin().
• Se apenas buyerReportingId estiver definido, buyerReportingId vai estar disponível.
• Se nem buyerAndSellerReportingId nem buyerReportingId forem definidos, o interestGroupName vai estar disponível.

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

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

O ID de relatórios que fica disponível em reportWin() é verificado quanto à k-anonimização 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 é excluído dessa verificação até pelo menos o primeiro trimestre de 2025. Se a verificação de k-anonimato falhar, o reportWin() ainda será executado, mas o valor do ID de relatório não estará disponível na função.

Apenas 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 fica disponível dentro de reportWin():

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

Antes de ficar disponível para reportWin(), a buyerReportingId é 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 primeiro trimestre de 2025).

Somente buyerAndSellerReportingId está 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 fica 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 lances, 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 primeiro trimestre de 2025).

buyerAndSellerReportingId e buyerReportingId estão definidos

Se buyerAndSellerReportingId e buyerReportingId forem 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',
  }]
});

Nesse caso, apenas buyerAndSellerReportingId está disponível em reportWin() devido ao comportamento de substituição:

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

Antes de ficar disponível para reportWin(), a buyerAndSellerReportingId é verificada para k-anonimato 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 primeiro trimestre de 2025).

Nem buyerAndSellerReportingId nem buyerReportingId foram definidos.

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

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

Em seguida, o grupo de interesse name fica disponível em reportWin():

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

Antes de ficar disponível para reportWin(), o nome do grupo de interesse (interestGroupName) é verificado para k-anonimato com o proprietário do grupo de interesse, 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 primeiro trimestre de 2025).

IDs de relatórios selecionáveis

Disponibilidade de IDs de relatórios com ID de relatório selecionável

Os IDs de relatórios selecionáveis permitem que um comprador selecione um ID durante a geração de lances, e o navegador disponibiliza o valor selecionado para scoreAd() e funções de relatórios. 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órios de cada anúncio. As funções de relatório do comprador e do vendedor só vão ser executadas para o anúncio vencedor, e as funções vão receber os IDs de relatório definidos para esse anúncio.

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

Observação: os IDs de relatórios selecionáveis vão estar disponíveis na versão estável na 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 IDs de relatórios selecionável (selectableBuyerAndSellerReportingIds) é uma matriz de strings definidas pelo comprador no grupo de interesses 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 lances do comprador

Se selectableBuyerAndSellerReportingIds foi definido na configuração do grupo de interesse, ele fica disponível em generateBid() com outros IDs de relatórios definidos.

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

  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 será 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 vão voltar ao 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 k-anônimo junto com buyerAndSellerReportingId (se presente), buyerReportingId (se presente), 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 está excluído desta verificação até pelo menos o primeiro trimestre de 2025).

Observação: nos casos em que a generateBid() é executada 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 passam 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 que foi devolvido pelo comprador de generateBid() fica disponível em scoreAd(), junto com o buyerAndSellerReportingId, se ele tiver sido definido na configuração do grupo de interesse.

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

  // ...
}

Relatórios do vendedor

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

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

Se selectableBuyerAndSellerReportingIds foi definido na configuração do grupo de interesse e selectedBuyerAndSellerReportingId foi retornado de generateBid(), ele não poderá vencer o leilão, a menos que selectedBuyerAndSellerReportingId e buyerAndSellerReportingId (se presentes) sejam k-anônimos com o proprietário do grupo de interesse, URL do script de lance, URL de renderização e tamanho do anúncio (o tamanho do anúncio é excluído desta 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 para selectedBuyerAndSellerReportingId, isso significa que os IDs de relatórios passaram na verificação de k-anonimato, e todos os IDs de relatórios definidos vão estar disponíveis em reportResult().

Relatórios do comprador

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

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

  // ...
}

Regras de substituição

Aqui, resumimos as regras de substituição para IDs de relatórios não selecionáveis e selecionáveis. O navegador determina qual dos valores selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId e o nome do grupo de interesse é transmitido para reportWin() 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) estarão 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 for definido no grupo de interesse, somente buyerReportingId estará disponível para geração de relatórios.
• Caso contrário, apenas o grupo de interesse name estará disponível para geração de relatórios.

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

Os IDs de relatórios estã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) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definido) 3) buyerReportingId (se definido)	1) selectedBuyerAnd 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 denúncia, consulte a seção ID de denúncia da explicação sobre o público-alvo protegido.
• GitHub: faça perguntas e siga a discussão em problemas no repositório da API.
• W3C: discuta casos de uso do setor na reunião do WICG.
• Avisos: participe ou acesse a lista de e-mails.
• Suporte para desenvolvedores do Sandbox de privacidade: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade.
• Chromium: registre um bug do Chromium para fazer perguntas sobre a implementação disponível para teste no Chrome.