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 podem ser usados para gerar e pontuar lances e criar 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, que são abordadas neste guia.

Com os IDs de relatórios, você pode informar um identificador de um anúncio e ativar casos de uso, como ofertas.

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 do uso de IDs de relatórios selecionáveis. 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, junto com IDs de relatórios não selecionáveis, se necessário, todos os IDs definidos ficam disponíveis em generateBid() e scoreAd() também.

IDs de relatórios não 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órios do comprador e do vendedor só serão executadas para o anúncio vencedor e receberão os IDs de relatórios definidos para ele.

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 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 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 em reportResult(), ele é verificado quanto 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 é 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órios não estará disponível dentro dela.

Relatórios do comprador

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

• Se buyerAndSellerReportingId e buyerReportingId forem definidos, buyerAndSellerReportingId vai substituir buyerReportingId e estará disponível em reportWin().buyerAndSellerReportingId
• Se apenas buyerReportingId estiver definido, buyerReportingId vai estar disponível.
• Se buyerAndSellerReportingId e buyerReportingId não 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 disponível em reportWin() é verificado quanto 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 é excluído dessa verificação até pelo menos o primeiro trimestre de 2025). Se ela não passar na verificação de k-anonimato, reportWin() ainda será executado, mas o valor do ID de relatórios não estará disponível na função.

Apenas buyerReportingId está definido

Se apenas buyerReportingId estiver 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',
  }]
});

Assim, o buyerReportingId fica disponível no reportWin():

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

Antes de ficar disponível para reportWin(), o buyerReportingId é verificado quanto 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 é excluído dessa verificação até pelo menos o 1º trimestre de 2025).

Somente buyerAndSellerReportingId é definido

Se apenas buyerAndSellerReportingId estiver 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',
  }]
});

Assim, o buyerAndSellerReportingId fica disponível no reportWin():

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

Antes de ficar disponível para reportWin(), o buyerAndSellerReportingId é verificado quanto 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 é excluído dessa verificação até pelo menos o 1º trimestre de 2025).

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

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

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

Antes de ficar disponível para reportWin(), o buyerAndSellerReportingId é verificado quanto 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 é excluído dessa verificação até pelo menos o 1º trimestre de 2025).

Nem buyerAndSellerReportingId nem buyerReportingId estão definidos

Se nenhum dos IDs de relatórios estiver 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`,
  }]
});

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 quanto 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 será excluído dessa verificação até pelo menos o primeiro trimestre de 2025).

IDs de relatórios selecionáveis

Com os IDs de relatórios selecionáveis, um comprador pode escolher 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 a 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 de cada anúncio. As funções de relatórios do comprador e do vendedor só serão executadas para o anúncio vencedor e receberão os IDs de relatórios definidos para ele.

Quando IDs de relatórios não selecionáveis são usados 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, que só estavam disponíveis em funções de relatórios, os IDs de relatórios selecionáveis permitem que os IDs de relatórios não selecionáveis também fiquem disponíveis em generateBid() e scoreAd().

Grupo de interesse

O campo de IDs de relatórios selecionáveis (selectableBuyerAndSellerReportingIds) é uma matriz de strings definida pelo comprador no grupo de interesse de um anúncio. Também é possível definir IDs de relatório não selecionáveis junto com IDs de relatório 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() junto com outros IDs de relatório 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 estiver 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 será excluído dessa verificação até pelo menos o primeiro trimestre de 2025).

Pontuação de anúncios do vendedor

Para o vendedor, o selectedBuyerAndSellerReportingId retornado pelo comprador de generateBid() fica disponível em scoreAd(), junto com buyerAndSellerReportingId, se ele foi 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 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 presente) sejam 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 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 estarão 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 de 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;

  // ...
}

Substituir regras

Aqui, resumimos as regras de substituição para IDs de relatórios não selecionáveis e selecionáveis. Qual dos itens selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId e o nome do grupo de interesse são transmitidos para reportWin() é determinado 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) estarão disponíveis para geração de relatórios.
• Caso contrário, se buyerAndSellerReportingId estiver 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, somente buyerReportingId estará disponível para geração de relatórios.
• Caso contrário, apenas o grupo de interesse name estará disponível para relatórios.

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

Interagir e compartilhar feedback

• Para saber mais sobre os IDs de relatório, consulte a seção "ID de relatório" da explicação da API Protected Audience.
• GitHub: faça perguntas e acompanhe a discussão em problemas no repositório da API.
• W3C: fale sobre os casos de uso do setor na chamada do WICG (link em inglês).
• Anúncios: participe ou confira 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.