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

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

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

Leia o guia para desenvolvedores para conferir o ciclo de vida completo da API Protected Audience e consulte a explicação sobre ela para conferir uma discussão mais detalhada sobre os relatórios de eventos (temporários).

Você não é um desenvolvedor? Consulte a visão geral da API Protected Audience.

O que o relatório da API Protected Audience?

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

  • Relatório do vendedor: informa o vendedor sobre o vencedor do leilão de anúncios.
  • Relatório do comprador: 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 os compradores com as APIs Private agregação. Como um 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 pode chamar a função sendReportTo(). Isso usa um único argumento: uma string que representa um URL buscado após a conclusão do leilão e que codifica as 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 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 fornecendo 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 passados para essa função são:

auctionSignals e perBuyerSignals

Os mesmos valores transmitidos ao generateBid() para o bidder vencedor.

sellerSignals

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

browserSignals

Um objeto construído pelo navegador fornecendo 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 gerar 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, em scoreAd() e generateBid(), com argumentos de URL diferentes.

O Chrome só envia relatórios de depuração de perda/ganhos 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 ficam disponíveis por padrão no Chrome se chrome://flags/#privacy-sandbox-ads-apis estiver ativado. No entanto, se você estiver executando o Chrome com sinalizações de linha de comando para ativar a API Protected Audience, será necessário 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.

A seguir

Queremos conversar com você para garantir a criação de uma API que funcione para todos.

Converse sobre a API

Assim como outras APIs do Sandbox de privacidade, essa API é documentada e discutida publicamente.

Teste a API

Você pode fazer testes e participar de conversas sobre a API Protected Audience.