Relatórios de leilão da API Protected Audience

Medir dados e resultados de 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 em um leilão de anúncios, a API Protected Audience funciona com:

• Agregação privada, que coleta indicadores e resultados de leilão para gerar relatórios de resumo
• A API Ads Reporting para Fenced Frames e iframes, que é um canal dentro dos frames para se comunicar com os worklets da API Protected Audience. A API permite associar dados do evento a indicadores de leilão. Os relatórios de eventos da API Ads Reporting são um mecanismo de transição até que um mecanismo com mais privacidade seja desenvolvido.
• API Attribution Reporting, que 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 relatar esses dados depois usando a agregação privada.

Visão geral dos relatórios da API 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 seu servidor: o momento do leilão, quando o leilão é executado no site do editor, o momento da renderização quando o anúncio é renderizado em um frame isolado ou um iframe no site do editor e o momento da conversão quando o usuário realiza alguma ação em outro site que pode ser atribuída ao leilão.

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

Locais dos relatórios

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

Durante cada um dos períodos listados, compradores e vendedores terão acesso a várias APIs de relatórios disponíveis para gerar relatórios sobre dados, como indicadores de leilão, dados no nível do 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 por um worklet da API Protected Audience durante o leilão.

Indicadores

Indicadores são os dados contextuais do leilão, do usuário, em tempo real e do navegador disponíveis para compradores e vendedores em um worklet para gerar um lance, classificar um anúncio e relatar os resultados de um leilão.

O objeto de configuração do leilão é a principal fonte de dados fornecida para disponibilização como indicadores em worklets. O editor e o vendedor podem fornecer dados contextuais e próprios na configuração do leilão, e esses indicadores podem ser enriquecidos 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 do comprador/vendedor, faturamento, orçamento, treinamento do modelo de ML e muito mais.

Outros dados disponíveis

• Dados de resultados relacionados a dados de vitórias e derrotas no leilão, como preço do lance vencedor e motivo da rejeição do lance.
• Dados de desempenho que contêm informações de latência, como quanto tempo levou para buscar e executar o worklet de lances.

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

Fora de um leilão da API Protected Audience, há dois períodos em que os dados ficam disponíveis para serem informados.

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 seu servidor. Exemplos de dados no nível do evento incluem impressão do anúncio, taxa de cliques, passagem do cursor e outros eventos que ocorrem no frame.

Durante a conversão, quando um usuário realiza alguma ação na página de cliques 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 seu servidor.

Relatórios no nível do evento

Os relatórios de eventos 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 ganhos com o leilão no nível do evento vão continuar ativos, não vai ser necessário usar frames delimitados para renderizar anúncios com a API Protected Audience e use um iframe com acesso irrestrito à rede nos relatórios de eventos. Além disso, a API Ads Reporting está disponível em frames e iframes isolados para que você associe dados de leilão e conversão a dados de evento do frame. Isso foi desenvolvido para facilitar a migração do ecossistema, já que você pode continuar usando sua infraestrutura de relatórios atual até pelo menos 2026, enquanto migra seu sistema para a API Protected Audience.

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

Um mecanismo disponível para informar dados no nível do evento em um leilão com Protected Audience é o sendReportTo() function em uma vitória do leilão. A função está disponível no worklets de relatórios do comprador e do vendedor, e o navegador faz uma solicitação GET à string de 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 do worklet 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 de reportResult() e um relatório de vitórias para o comprador quando chamada de reportWin(). A função sendReportTo() está disponível pelo menos até 2026,

Relatório de engajamento

Um relatório de engajamento contém dados no nível do evento de um criativo de anúncio, como dados de impressão ou clique, 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 do leilão não ficam disponíveis dentro do frame que renderiza o anúncio. Para associar esses dados de períodos diferentes, oferecemos dois mecanismos de transição que geram relatórios de engajamento.

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. No entanto, ela não funciona para um frame isolado, já que um ID exclusivo não pode ser transmitido do incorporador porque a comunicação entre o incorporador e o frame isolado é limitada. Para associar os dados de leilão a informações de evento de um anúncio de frame isolado, é possível usar a API Ads Reporting.

API Ads Reporting para frames e iframes isolados

A API Ads Reporting para frames e iframes isolados oferece um mecanismo para associar dados 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 do relatório com os indicadores adicionados como parâmetros de consulta. Você também especifica o evento personalizado que gostaria de 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 dentro do frame isolado podem ser adicionados como o payload.

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

No exemplo a seguir, um ID de campanha é associado a um payload no nível do 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 pelo menos até 2026 pelos mesmos motivos que os relatórios de vitórias.

Se quiser mais detalhes, confira a explicação.

Acesso irrestrito à rede

Os frames delimitados permitem o carregamento de recursos de rede da mesma forma que um iframe, e é possível enviar dados no nível do evento dentro de frames isolados para o servidor. É possível gerar relatórios de eventos no lado do servidor posteriormente associando os dados no nível do evento de um frame isolado aos dados de leilão enviados com sendReportTo(). Isso foi discutido na seção acima sobre mecanismo de denúncias no nível do evento de leilão.

O acesso à rede será restrito no futuro.

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 que foi 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.

Estamos desenvolvendo uma solução mais permanente, mas você pode usar a API Ads Reporting para frames isolados como um mecanismo de transição para gerar um relatório agregável e de evento com o Attribution Reporting. Esses relatórios servem para medir a conversão e são separados dos relatórios de engajamento agregáveis e de evento gerados a partir do leilão e do frame de anúncios. Quando tudo estiver pronto, vamos publicar uma explicação para uma solução mais permanente.

Mecanismo transicional

Ao registrar um beacon de anúncio, você pode usar a palavra-chave reserved.top_navigation, que adicionará automaticamente o cabeçalho Attribution-Reporting-Eligible para que o beacon se qualifique para registro 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 "API 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 de anúncios e do site de conversão.

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:

1. 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.
2. Durante o leilão, o comprador pode registrar um beacon de anúncio para ser acionado durante a renderização do anúncio e o momento da conversão (registerAdBeacon()).
   1. Para associar indicadores de leilão a um evento de frame de anúncios, 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.
3. 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.
4. Durante o momento da conversão, você pode acionar a origem registrada no momento do 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 única 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. Além disso, 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 da API Protected Audience e gerar um relatório de resumo, um relatório agregado e ruído de dados coletados em buckets. Um bucket é representado por uma chave de agregação, e algumas informações podem ser codificadas na chave.

Por exemplo, um evento de impressão de anúncio pode ser contado em diferentes intervalos, em que cada intervalo representa uma campanha publicitária distinta. Um relatório de resumo difere 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 acessaram a campanha 123 e o ruído foi adicionado para proteger a privacidade do usuário.

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 privada. Para a agregação de indicadores, use o método privateAggregation.contributeToHistogram() disponível no worklet de lances do comprador, no worklet de pontuação do vendedor e no trabalho de relatórios 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 nem são acionados por um evento fora do leilão. Para saber mais sobre os relatórios dos indicadores de leilão, consulte a explicação.

Como agregar indicadores de leilão com 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 forma agregada quantos cliques um anúncio de uma campanha recebeu. Para isso, crie um grupo que representa essa campanha e o evento de clique. No frame de anúncio, é possível especificar qual evento ocorreu, mas não anexar uma carga útil no nível do evento.

Para agregar indicadores de leilão por eventos, use privateAggregation.contributeToHistogramOnEvent(eventType, contribution), que recebe 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 avaliar quantos cliques um 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 lances, você pode definir um grupo como a combinação do ID da campanha e do evento de clique e, em seguida, aumentar o valor desse grupo em 1 sempre que o evento for acionado.

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

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

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

Geração de relatórios sobre a performance e os resultados do leilão

Você também pode agregar os resultados do leilão quando acionado por um evento de vitória ou derrota do leilão com contributeToHistogramOnEvent(eventType, contribution) ao transmitir palavras-chave de tipo de evento reservadas (reserved.win, reserved.loss e reserved.always).

A agregação particular oferece 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 que recebeu a segunda pontuação mais alta e o motivo da rejeição de um lance no leilão.

Quando um valor de base é fornecido, como o 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 indicado como o valor base, você poderá subtrair seu lance de R $2,00 para calcular o valor real de R $3,00 de quanto perdeu seu leilão.

Relatórios de resultados do leilão

Vejamos um exemplo em que você perdeu um leilão e quer saber qual foi a distância entre o lance e o preço de arrecadação do leilão.

Para saber quanto você perdeu no leilão, subtraia o preço do seu 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 é enviado, o valor real informado é a baseValue dimensionada, deslocada para o valor de offset. Para mais detalhes, consulte a explicação.

Relatórios de desempenho

Os compradores e vendedores podem informar quanto tempo levou para um script 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 lances confiáveis de cada comprador com a permissão dele.

Consulte 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 você pode 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 dentro de um worklet e relatar esses valores usando a agregação privada do worklet.

Também é possível gravar no armazenamento compartilhado dos worklets de relatórios, pontuação e lances da API Protected Audience. Depois, é possível relatar esses valores no armazenamento compartilhado para seu servidor usando a agregação privada . Também é possível usar os valores armazenados para a operação de seleção de URL.

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

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

Depois, é possível carregar um 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, a explicação, a demonstração ao vivo e o código de demonstração no GitHub.

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.