Esta página foi traduzida pela API Cloud Translation.

Relatórios de leilão da API Protected Audience

Medir os dados e os resultados do leilão da API Protected Audience

Neste artigo, você vai encontrar uma visão geral de alto nível dos vários mecanismos disponíveis para informar dados de leilão da API Protected Audience ao seu servidor, além dos mecanismos de transição disponíveis para uso durante a migração até que soluções alternativas estejam prontas.

Para gerar relatórios sobre métricas importantes coletadas de um leilão de anúncios, a API Protected Audience funciona com:

Agregação privada: coleta indicadores e resultados do leilão para gerar relatórios de resumo.
API Ads Reporting para Fenced Frames e iframes, que são um canal nos frames para se comunicar com os worklets da API Protected Audience. A API permite associar dados no nível do evento a indicadores de leilão. Os relatórios de eventos da API Ads Reporting funcionam como um mecanismo de transição até que um mecanismo de geração de relatórios mais particular seja criado.
Attribution Reporting: permite associar dados de conversão a indicadores de leilão.
Armazenamento compartilhado, que permite gravar indicadores de leilão em um armazenamento de origem cruzada e depois relatar esses dados usando a agregação privada.

Visão geral dos relatórios da API Protected Audience

Fluxo de trabalho geral da Protected Audience

Há três períodos principais em que os dados do fluxo de leilão da API Protected Audience podem ser informados ao servidor: o momento do leilão, quando o leilão é executado no site do editor, o tempo de renderização quando o anúncio é renderizado em um frame isolado ou em um iframe no site do editor e o momento da conversão em que o usuário realiza alguma ação em outro site que possa ser atribuída ao leilão.

Durante o leilão, é possível informar os dados do leilão usando os worklets de relatório. Durante o tempo de renderização, é possível gerar relatórios sobre os dados de engajamento de um iframe ou um frame isolado. Durante a conversão, é possível registrar os dados de atribuição da página de destino usando a API Attribution Reporting.

Locais do relatório

Em um leilão, os compradores podem informar os indicadores disponíveis nos workers generateBid() e reportWin(), e os vendedores podem informar os indicadores disponíveis em scoreAd() e reportResult(). Fora de um leilão, os compradores e vendedores podem informar dados de um frame que processou o anúncio e do site em que a conversão foi feita.

Período	Destino	Local	Há dados disponíveis	APIs Reporting disponíveis
Leilão	Negociante	`generateBid()`	Indicadores, resultados e performance do leilão	API Private Aggregate
	Negociante	`reportWin()`		API Private Aggregate API Ads Reporting
	Vendedor	`scoreAd()`		API Private Aggregate
	Vendedor	`reportResult()`		API Private Aggregate API Ads Reporting
Renderizar	Comprador / Vendedor	Frame no site do editor	Dados de evento no frame do anúncio	API Private Aggregate API Ads Reporting
Conversão	Comprador / Vendedor	Site de conversão	Dados de conversão e de evento do site de conversão	API Attribution Reporting API Private Aggregate API Ads Reporting

Durante cada um dos períodos listados, os compradores e vendedores terão acesso a várias APIs de relatórios disponíveis para informar dados, como indicadores de leilão, dados de evento e dados de conversão.

Dados disponíveis em um leilão da API Protected Audience

Os dados a seguir estão disponíveis para serem informados em um worklet da API Protected Audience durante o leilão.

Indicadores

Os indicadores são os dados contextuais do leilão, do usuário, em tempo real e do navegador disponíveis aos compradores e vendedores em uma planilha para gerar um lance, pontuar um anúncio e informar os resultados de um leilão.

Indicador	Descrição	Definir local	Usuários	Disponibilidade
auctionSignals	Dados disponíveis no contexto do local do leilão. Esses dados podem incluir informações do conteúdo da página, dados próprios do usuário e muito mais.	Definido pelo vendedor no site do editor na configuração do leilão.	Comprador Vendedor	generateBid scoreAd reportWin reportResult
directFromSellerSignals	Os mesmos dados para `auctionSignals`, `perBuyerSignals` e `sellerSignals`, mas os indicadores vêm do vendedor especificado.	Definido por meio de cabeçalhos de resposta HTTP do vendedor	Comprador Vendedor	generateBid scoreAd reportWin reportResult
browserSignals	Vários dados fornecidos pelo navegador (`topWindowHostname`, `interestGroupOwner`, `renderUrl`, `adComponents`, `biddingDurationMsec`, `IGJoinCount`, `IGRecency`, `modelingSignals`).	É definido pelo navegador.	Comprador Vendedor	generateBid scoreAd reportWin reportResult
sellerSignals	Indicadores fornecidos ao vendedor para pontuação do anúncio.	Definido pelo vendedor no site do editor na configuração do leilão.	Vendedor	scoreAd reportWin reportResult
trustedScoringSignals	Indicadores em tempo real fornecidos ao vendedor para pontuação do anúncio.	O URL é definido pelo vendedor no site do editor na configuração do leilão.	Vendedor	scoreAd reportResult
perBuyerSignals	Dados contextuais do leilão fornecidos a compradores específicos. O vendedor pode recuperar os valores dos compradores antes do início do leilão. São as informações que o comprador tem sobre a oportunidade de anúncio.	Definido pelo vendedor no site do editor na configuração do leilão.	Negociante	generateBid scoreAd reportWin reportResult
trustedBiddingSignals	Indicadores em tempo real fornecidos aos compradores para lances de anúncios.	O URL é definido pelo comprador no site do anunciante quando o grupo de interesse é definido.	Negociante	generateBid
userBiddingSignals	Dados do usuário fornecidos pelo comprador.	Definido pelo comprador no site do anunciante quando o grupo de interesse for definido .	Negociante	generateBid

O objeto de configuração do leilão é a principal fonte de dados fornecidos para disponibilização como sinais em worklets. O editor e o vendedor podem fornecer dados próprios e contextuais na configuração do leilão. Esses indicadores podem ser aprimorados com os dados do grupo de interesse do comprador, dados no nível do evento do frame de renderização do anúncio e dados de atribuição da página de cliques. Os dados informados podem ser usados para relatórios de comprador/vendedor, faturamento, orçamento, treinamento de modelos de ML e muito mais.

Outros dados disponíveis

Dados de resultados relacionados a dados de ganhos e perdas de leilões, como preço do lance vencedor e motivo da rejeição do lance.
Dados de desempenho com informações de latência, como o tempo necessário para buscar e executar o worklet de lances.

Dados disponíveis fora de um leilão da API Protected Audience

Fora do leilão da API Protected Audience, há dois períodos em que os dados estão disponíveis para geração de relatórios.

Durante o tempo de renderização, quando o anúncio é renderizado no site do editor, os dados no nível do evento de dentro do iframe ou do frame isolado podem ser associados aos dados de leilão da API Protected Audience e informados ao servidor. Alguns exemplos de dados no nível do evento incluem impressão de anúncio, taxa de cliques, passagem do cursor e outros eventos que ocorrem dentro do frame.

Durante o momento da conversão, quando um usuário realiza uma ação na página de cliques que é atribuída ao leilão, os dados no nível do evento da página de conversão podem ser associados aos dados de leilão da API Protected Audience e informados ao servidor.

Relatórios no nível do evento

Os relatórios de evento detalham informações de um ou mais eventos. Um evento pode ser uma vitória no leilão, uma impressão de anúncio ou uma conversão. Até pelo menos 2026, os relatórios de vitórias no leilão no nível do evento vão continuar em vigor, os frames isolados não vão ser necessários para renderizar um anúncio da API Protected Audience e um iframe com acesso ilimitado à rede pode ser usado para relatórios no nível do evento. Além disso, a API Ads Reporting está disponível em frames e iframes isolados para associar dados de leilão e conversão a dados de evento do frame. Isso foi feito para facilitar a migração do ecossistema, já que você pode continuar usando sua infraestrutura de relatórios atual pelo menos até 2026 enquanto migra seu sistema para a API Protected Audience.

Relatórios de vitórias no leilão no nível do evento com o `sendReportTo()`

Um mecanismo disponível para relatar dados no nível do evento em um leilão da Protected Audience é o sendReportTo() function em uma vitória de leilão. A função está disponível nos worklets de relatórios do comprador e do vendedor, e o navegador faz uma solicitação GET à string do URL fornecida quando a renderização do anúncio começa. É possível codificar qualquer sinal disponível nos seus worklets como parâmetros de consulta do URL.

Por exemplo, um comprador pode informar o valor do lance vencedor da ferramenta reportWin() para fins de faturamento:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

A função sendReportTo() pode ser usada para gerar um relatório de vitórias para o vendedor quando chamada no método reportResult() e um para o comprador quando chamada de reportWin(). A função sendReportTo() está disponível pelo menos até 2026,

Relatório de envolvimento

Um relatório de engajamento contém dados no nível do evento de um criativo de anúncio, como dados de impressões ou cliques, que estão associados aos indicadores do leilão da API Protected Audience que renderizou o anúncio. Como o anúncio é renderizado após a conclusão do leilão, os indicadores dele não ficam disponíveis dentro do frame que renderiza o anúncio. Para associar esses dados de períodos diferentes, fornecemos dois mecanismos de transição para gerar relatórios de envolvimento.

A função sendReportTo() descrita acima pode ser usada para associar dados de leilão a dados no nível do evento de um iframe, mas não funciona para um frame isolado, já que um ID exclusivo não pode ser transmitido do embedder porque a comunicação entre ele e o frame isolado é limitada. Para associar dados de leilão a dados de evento de um anúncio de frame isolado, use a API Ads Reporting.

API Ads Reporting para frames delimitados e iframes

A API Ads Reporting para frames e iframes isolados oferece um mecanismo para você associar dados no nível do evento do usuário de um frame de anúncio a indicadores em um leilão da API Protected Audience.

Em um worklet de relatórios da API Protected Audience, é possível registrar um beacon de anúncio com a função registerAdBeacon() e transmitir o URL com os indicadores adicionados como parâmetros de consulta. Você também especifica o evento personalizado que quer associar ao URL do relatório. Depois, quando o anúncio for renderizado em um frame isolado, será possível acionar o evento personalizado chamando a função window.fence.reportEvent(). Os dados disponíveis no frame isolado podem ser adicionados como o payload.

A função registerAdBeacon() está disponível somente nas funções de relatórios e não está disponível na lógica de lances do comprador nem na lógica de pontuação do vendedor.

No exemplo a seguir, um ID de campanha é associado a um payload em nível de evento com as coordenadas de clique:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

A API Fenced Frames Ads Reporting também vai estar disponível até pelo menos 2026 pelos mesmos motivos dos relatórios de vitórias.

Para mais detalhes, consulte a explicação.

Acesso ilimitado à rede

Os frames delimitados permitem o carregamento de recursos de rede da mesma forma que um iframe, e você pode enviar dados no nível do evento dentro de frames delimitados para seu servidor. É possível gerar relatórios de eventos no lado do servidor mais tarde associando os dados de evento de um frame isolado aos dados de leilão enviados com sendReportTo(). Esses dados foram discutidos na seção Mecanismo de relatórios no nível do evento do leilão acima.

O acesso à rede será restrito após a descontinuação dos cookies de terceiros.

Os mecanismos de geração de relatórios de eventos que existem na API Protected Audience atualmente são mecanismos de transição, e uma solução alternativa será projetada para oferecer um suporte melhor aos casos de uso atuais.

Relatório de atribuição

Um Relatório de atribuição permite associar uma conversão em um site a um anúncio escolhido em um leilão da API Protected Audience. Por exemplo, um usuário pode clicar em um anúncio de produto que você veicula, ser redirecionado para o site do anunciante, fazer uma compra nele e você tem interesse em atribuir a compra ao anúncio exibido. A API Attribution Reporting será integrada à API Protected Audience para combinar os dados de leilão do site do editor e os dados de conversão do site do anunciante.

Embora desenvolvemos uma solução mais permanente, você pode usar a API Ads Reporting para frames delimitados como um mecanismo de transição para gerar um relatório agregável e no nível do evento com a API Attribution Reporting. Esses relatórios servem para medir conversões e são separados dos relatórios de engajamento agregáveis e no nível do evento gerados no leilão e no frame do anúncio. Publicaremos uma explicação para uma solução mais permanente quando estiver tudo pronto.

Mecanismo de transição

Ao registrar um beacon de anúncio, você pode usar a palavra-chave reserved.top_navigation. Ela adiciona automaticamente o cabeçalho Attribution-Reporting-Eligible para que o sensor se qualifique para se registrar como uma fonte de atribuição.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Para anexar dados de evento ao beacon registrado, chame setReportEventDataForAutomaticBeacons() no frame isolado com o payload do evento.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Consulte a seção Attribution Reporting da explicação da API Ads Reporting para saber mais.

Exemplo de relatório de engajamento e conversão

Neste exemplo, vamos analisar a perspectiva do comprador, que está interessado em associar os dados do leilão, do frame do anúncio e do site de conversão juntos.

Nesse fluxo de trabalho, o comprador coordena com o vendedor para enviar um ID exclusivo ao leilão. Durante o leilão, o comprador envia esse ID exclusivo com os dados do leilão. Durante a renderização e a conversão, os dados do frame isolado ou do iframe também são enviados com o mesmo ID exclusivo. Depois, o ID exclusivo pode ser usado para associar esses relatórios.

Fluxo de trabalho:

Antes do início do leilão, o comprador envia um ID exclusivo ao vendedor como parte da resposta do lance em tempo real ("RTB") (link em inglês) programática. O ID pode ser definido como uma variável, como auctionId. O ID é transmitido como perBuyerSignals no auctionConfig e fica disponível nos worklets do comprador.
Durante o leilão, o comprador pode registrar um beacon de anúncio para ser acionado durante o processamento do anúncio e o momento da conversão (registerAdBeacon()).
1. Para associar indicadores de leilão a um evento de frame de anúncio, defina auctionId como um parâmetro de consulta do URL de beacon.
2. Para associar indicadores de leilão a um evento de conversão, defina auctionId no URL de beacon.
Durante a renderização do anúncio, os beacons registrados no momento do leilão podem ser acionados ou aprimorados com dados de evento.
1. Acione o evento do frame com reportEvent() e transmita os dados no nível do evento.
2. Adicionar payload no nível do evento ao beacon de atribuição com setReportEventDataForAutomaticBeacons()
3. Registre o anúncio com a API Attribution Reporting respondendo às solicitações de beacon de anúncio com o cabeçalho Attribution-Reporting-Register-Source.
Durante a data/hora da conversão, é possível acionar a origem registrada durante o leilão.

Após o processo acima, o comprador terá um relatório de leilão, de engajamento e de conversão, todos vinculados por uma chave exclusiva que pode ser usada para associação entre si.

Um fluxo de trabalho semelhante será aplicado a um vendedor se ele precisar de acesso aos dados de atribuição. O vendedor também poderá usar um ID exclusivo para enviar com registerAdBeacon(). No frame, a chamada reportEvent() contém uma propriedade de destino que pode ser usada para enviar o relatório ao comprador e ao vendedor. A SSP também precisa estar presente na página de destino para que o acionador seja atribuído à origem.

Como agregar dados da API Protected Audience

A API Private Aggregate é o mecanismo usado para informar dados de público protegido e gerar um relatório de resumo, que é um relatório agregado e com ruído de dados coletados em buckets. Um bucket é representado por uma chave de agregação, e algumas informações podem ser codificadas nessa chave.

Por exemplo, um evento de impressão de anúncio pode ser contado em intervalos diferentes, em que cada segmento representa uma campanha publicitária diferente. Um relatório de resumo é diferente de um relatório de evento porque não revela informações sobre cada evento individual. Com um relatório de evento, é possível determinar que os usuários A, B e C viram a campanha 123. Com os relatórios de resumo, é possível medir o número de usuários que viram a campanha 123, e o ruído é adicionado para proteger a privacidade deles.

Consulte o artigo Agregação privada para saber mais sobre a API.

Como agregar indicadores de leilão

É possível agregar os sinais disponíveis nos worklets ao seu servidor usando a agregação particular. Para agregação de indicadores, use o método privateAggregation.contributeToHistogram() disponível na worklet de lances do comprador, na worklet de pontuação do vendedor e nos workers de relatório do comprador/vendedor.

Neste exemplo, o lance vencedor é agregado ao grupo de proprietários do grupo de interesse:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
}

Esse é o mecanismo geral a ser usado quando os indicadores que você quer agregar não estão associados a dados no nível do evento e não são acionados por um evento fora do leilão. Para saber mais sobre como gerar relatórios de indicadores de leilão, consulte a explicação.

Como agregar indicadores de leilão a dados de eventos

É possível agregar indicadores de leilão com informações limitadas sobre um evento que ocorre em um frame de anúncio. Por exemplo, é possível medir de maneira agregada quantos cliques um anúncio de uma campanha recebeu criando um grupo que representa essa campanha e o evento de clique. No frame do anúncio, você pode especificar qual evento ocorreu, mas não é possível anexar uma carga útil no nível do evento.

Para agregar indicadores de leilão por eventos, use privateAggregation.contributeToHistogramOnEvent(eventType, contribution), que usa uma string que especifica o tipo de evento e a contribuição a ser informada quando ele for acionado. É possível chamar o método com um tipo de evento personalizado e, em seguida, chamar window.fence.reportEvent(eventType) no frame do anúncio para acionar o relatório a ser enviado.

Digamos que você queira medir quantos cliques o anúncio de uma campanha recebeu.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

Na função de geração de lance, é possível definir um intervalo como a combinação do ID da campanha e do evento de clique e, em seguida, aumentar o valor desse segmento em 1 sempre que o evento for acionado.

// Ad frame
window.fence.reportEvent('click');

Depois, no frame do anúncio, é possível acionar o envio do relatório chamando reportEvent(eventType):

Saiba mais sobre como acionar contribuições de agregação privada em um frame na explicação.

Como gerar relatórios sobre o desempenho e os resultados do leilão

Também é possível agregar resultados do leilão quando acionado por um evento de vitória ou derrota com contributeToHistogramOnEvent(eventType, contribution) ao transmitir palavras-chave de tipo de evento reservado (reserved.win, reserved.loss e reserved.always).

A agregação particular apresenta uma lista de valores base que podem ser usados para calcular o bucket e o valor da contribuição. Os valores base disponíveis para os resultados do leilão são o valor do lance do anúncio vencedor, o valor do lance com a segunda pontuação mais alta e o motivo da rejeição de um lance no leilão.

Quando algum valor base é fornecido, como o valor do lance vencedor, você pode definir quanto adicionar ou subtrair desse valor e informar o valor final. Por exemplo, se o lance vencedor de R $5,00 for fornecido como o valor base, você poderá subtrair o lance de R $2,00 para calcular o valor real de R $3,00 de acordo com o valor do leilão.

Relatórios de resultados do leilão

Vejamos um exemplo em que você perdeu um leilão e deseja saber qual foi a diferença de valor entre seu lance e o preço de arrecadação.

Para saber quanto você perdeu no leilão, é possível subtrair o preço do lance do preço do lance vencedor:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Quando o relatório for enviado, o valor real informado será a baseValue dimensionada alterada pelo valor offset. Para saber mais, consulte a explicação.

Relatórios de desempenho

Compradores e vendedores podem informar quanto tempo um script levou para ser executado e quanto tempo levou para buscar os indicadores confiáveis. Os vendedores podem coletar o horário de geração do lance e o horário do indicador de lance confiável de cada comprador com a permissão dele.

Acesse a explicação para saber mais.

Armazenar indicadores de leilão no Armazenamento compartilhado

O armazenamento compartilhado é um armazenamento não particionado e de origem cruzada em que é possível gravar livremente, mas é protegido com portões ao ler e processar os valores armazenados. Uma das portas disponíveis para a API Shared Storage é a agregação privada. Só é possível ler os valores no armazenamento compartilhado de dentro de um worklet e informar esses valores usando a agregação particular.

Também é possível gravar no armazenamento compartilhado usando os worklets de lances, de pontuação e de relatórios da API Protected Audience. Posteriormente, você poderá relatar esses valores no armazenamento compartilhado para seu servidor usando a agregação particular . Também é possível usar os valores armazenados para a operação Seleção de URL.

Em um worklet da API Protected Audience, é possível gravar todas as chaves e valores no armazenamento compartilhado:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

Mais tarde, é possível carregar uma worklet de armazenamento compartilhado para ler e enviar esse valor com a agregação privada:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Para saber mais sobre o armazenamento compartilhado, consulte a seção de armazenamento compartilhado do guia para desenvolvedores de relatórios da API Protected Audience, explicação, demonstração ao vivo e código de demonstração no GitHub (links em inglês).

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.