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

Guia para vendedores e compradores gerarem relatórios de leilão da API Protected Audience.

Este artigo é uma referência técnica para gerar relatórios sobre vitórias em leilões da API Protected Audience, conforme usado na iteração atual da API Protected Audience experimental.

Leia o guia para desenvolvedores para conhecer o ciclo de vida completo da API Protected Audience e consulte a explicação da API para uma discussão detalhada sobre relatórios no nível do evento (temporário).

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

O que a API Protected Audience informa?

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

• Relatório do vendedor: informa ao vendedor quem venceu o leilão de anúncios.
• Relatório do comprador: disponível apenas para os compradores vencedores, para informar que eles ganharam um leilão.

O plano de longo prazo é permitir que o navegador informe os resultados do leilão para o vendedor e os compradores com as APIs Private Aggregation. Como um mecanismo temporário de relatórios a nível de evento, o código que implementa reportResult() para o vendedor e reportWin() para o bidder vencedor pode chamar a função sendReportTo(). Ele usa um único argumento: uma string que representa um URL buscado após a conclusão do leilão e codifica informações no nível do evento a serem informadas.

Funções da API

Vendedor: reportResult()

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

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

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

auctionConfig

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

browserSignals

Um objeto criado 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 incluir uma função reportWin() para informar o resultado do leilão.

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

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

auctionSignals e perBuyerSignals

Os mesmos valores transmitidos para generateBid() do bidder vencedor.

sellerSignals

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

browserSignals

Um objeto criado 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 temporária de relató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 usa um único argumento: um URL a ser buscado após a conclusão do leilão. Eles podem ser chamados várias vezes, tanto em scoreAd() quanto em generateBid(), com argumentos de URL diferentes.

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

Esses métodos estão disponíveis por padrão no Chrome quando você ativa todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy. Se você estiver executando o Chrome com flags de linha de comando para ativar a API Protected Audience, será necessário ativar explicitamente os métodos incluindo a flag BiddingAndScoringDebugReportingAPI. Se a flag 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

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

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.