Gerar relatórios sobre os resultados do leilão da API Protected Audience

Guia do vendedor e do comprador para gerar relatórios de leilão da API Protected Audience.

Este artigo é uma referência técnica para gerar relatórios para Vitórias no leilão da API Protected Audience, conforme usado na iteração atual do experimento a API Protected Audience.

Leia o guia para desenvolvedores para a vida completa da API Protected Audience e confira a explicação sobre ela para conferir mais detalhes sobre relatórios no nível do evento (temporário).

Não é um desenvolvedor? Consulte a visão geral da API Protected Audience.

O que a API Protected Audience informa?

Há dois relatórios da API Protected Audience disponíveis:

  • Relatório do vendedor: informa o vencedor do leilão de anúncios.
  • Relatório de compradores: disponível apenas para os compradores vencedores para saber que eles venceram um leilão.

O plano de longo prazo é permitir que o navegador informe os resultados do leilão para o vendedor e compradores com as APIs Private Aggregate API. Como mecanismo temporário de geração de relatórios no nível do evento, o código que implementa reportResult() para o vendedor e reportWin() para o bidder vencedor, podem chame a função sendReportTo(). Esse argumento aceita um único argumento: uma string representando um URL buscado após a conclusão do leilão, codificando as informações no nível do evento que serão informadas.

Funções da API

Vendedor: reportResult()

O JavaScript do vendedor fornecido em decisionLogicUrl (que também fornece scoreAd()) podem incluir uma função reportResult() para informar o leilão. resultado.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Os argumentos passados para essa função são:

auctionConfig

O objeto de configuração do leilão transmitido para navigator.runAdAuction().

browserSignals

Um objeto construído pelo navegador que fornece informações sobre o leilão. Exemplo:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

O valor de retorno dessa função é usado como o argumento sellerSignals para a função reportWin() do bidder vencedor.

Comprador: reportWin()

O JavaScript do bidder vencedor (que também forneceu generateBid()) pode inclua uma função reportWin() para informar o resultado do leilão.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Os argumentos passados para essa função são:

auctionSignals e perBuyerSignals

Os mesmos valores transmitidos ao generateBid() do vencedor proponente.

sellerSignals

O valor de retorno de reportResult(), que dá ao vendedor um de transmitir informações ao comprador.

browserSignals

Um objeto construído pelo navegador que fornece informações sobre o leilão. Exemplo:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Implementação de relatórios temporários

Há dois métodos disponíveis temporariamente no Chrome para relatórios de leilão:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Cada um desses métodos tem um único argumento: um URL a ser buscado após o leilão concluído. Elas podem ser chamadas várias vezes, tanto em scoreAd() quanto em generateBid(), com diferentes argumentos de URL.

O Chrome só envia relatórios de perda/vitória de depuração quando um leilão é concluído. Se um leilão é cancelado (por exemplo, devido a uma nova navegação), nenhum relatório ser gerados.

Esses métodos ficam disponíveis por padrão no Chrome quando você ativa todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy. Se você está executando Chrome com sinalizações de linha de comando para ativar a API Protected Audience, você vai precisar ativar explicitamente os métodos, incluindo a sinalização BiddingAndScoringDebugReportingAPI. Se a sinalização não estiver ativada, os métodos ainda estarão disponíveis, mas não farão nada.

Todas as referências da API Protected Audience

Os guias de referência da API estão disponíveis:

A explicação da API Protected Audience também fornece detalhes sobre o suporte e as restrições de recursos.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.