Relatórios de leilão da API Protected Audience

Medir dados e resultados de leilões da API Protected Audience

Neste artigo, você vai encontrar uma visão geral dos vários mecanismos disponíveis para informar os dados do leilão da API Protected Audience ao seu servidor, além dos mecanismos de transição disponíveis agora para uso durante a migração até que as 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:

• A agregação privada, que coleta indicadores e resultados do 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 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 são um mecanismo de transição até que um mecanismo de relatórios mais privado seja projetado.
• A Attribution Reporting, que permite associar dados de conversão a indicadores de leilão.
• O Shared Storage permite gravar indicadores de leilão em um armazenamento de origem cruzada e gerar relatórios desses dados mais tarde usando a Private Aggregation.

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 ele é 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 informar os dados usando worklets de relatórios. Durante o tempo de renderização, é possível informar dados de engajamento de um iframe ou um frame isolado. Durante o tempo de conversão, é possível gerar relatórios de dados de atribuição da página de destino usando a API Attribution Reporting.

Como denunciar locais

Em um leilão, os compradores podem informar indicadores disponíveis nos worklets generateBid() e reportWin(), e os vendedores podem informar indicadores disponíveis em scoreAd() e reportResult(). Fora de um leilão, os compradores e vendedores podem gerar relatórios de dados de um frame que renderizou 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 informar 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 seguintes dados podem ser incluídos em relatórios de 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 para compradores e vendedores em um worklet para gerar um lance, pontuar um anúncio e informar os resultados de um leilão.

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

Outros dados disponíveis

• Dados de resultados relacionados a dados de vitória e derrota em leilões, como preço do lance vencedor e motivo da rejeição do lance.
• Dados de performance que contêm 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 de um leilão da API Protected Audience, há dois períodos em que os dados estão disponíveis para serem incluídos em relatórios.

Durante a renderização, quando o anúncio é renderizado no site do editor, os dados de evento de dentro do iframe ou do frame isolado podem ser associados aos dados do leilão da API Protected Audience e enviados ao seu servidor. Exemplos de dados no nível do evento incluem impressão de anúncio, clique, passar o cursor e outros eventos que ocorrem dentro do frame.

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

Relatórios no nível do evento

Os relatórios no nível do evento detalham informações de um ou mais eventos. Um evento pode ser uma vitória em um leilão, uma impressão de anúncio ou uma conversão. Até pelo menos 2026, os relatórios de vitórias em leilões no nível do evento vão continuar disponíveis, os frames isolados não serão necessários para renderizar um anúncio do Protected Audience, e um iframe com acesso irrestrito à rede poderá ser usado para relatórios no nível do evento. Além disso, a API Ads Reporting está disponível em frames isolados e iframes para que você possa associar dados de leilão e conversão a dados no nível do evento do frame. Isso foi criado 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 o Protected Audience.

Relatórios de vitórias em leilões no nível do evento com sendReportTo()

Um mecanismo disponível para gerar relatórios de 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 nos worklets de relatórios de compradores e vendedores, e o navegador faz uma solicitação GET para a string de URL fornecida quando a renderização do anúncio começa. É possível codificar qualquer indicador 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ória para o vendedor quando chamada de reportResult() e um relatório de vitória para o comprador quando chamada de reportWin(). A função sendReportTo() vai estar 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 associados aos indicadores do leilão da API Protected Audience que renderizou o anúncio. Como o anúncio é renderizado depois que o leilão é concluído, os indicadores não estão disponíveis no frame que renderiza o anúncio. Para associar esses dados de diferentes períodos, oferecemos dois mecanismos de transição para gerar 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, mas 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 dados de leilão a dados no nível do evento de um anúncio em frame isolado, use a API Ads Reporting.

API Ads Reporting para frames isolados e iframes

A API Ads Reporting para frames isolados e iframes oferece um mecanismo para 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 de relatório com os indicadores adicionados como parâmetros de consulta. Você também especifica o evento personalizado que quer associar à URL de geração de relatórios. Depois, quando o anúncio for renderizado em um frame isolado, você poderá 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 apenas nas funções de relatórios, não na lógica de lances do comprador e de pontuação do vendedor.

No exemplo a seguir, um ID de campanha está associado a um payload no nível do evento com as coordenadas do 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 dos relatórios de vitórias.

Para mais detalhes, consulte a explicação.

Acesso à rede sem restrições

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

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 veiculado por você, ser redirecionado para o site do anunciante e fazer uma compra. Nesse caso, você tem interesse em atribuir a compra ao anúncio mostrado. 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.

Enquanto criamos uma solução mais permanente, você pode usar a API Ads Reporting para frames isolados 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 são para medir a conversão e são separados dos relatórios de engajamento agregáveis e no nível do evento gerados pelo leilão e pelo frame do anúncio. Vamos publicar uma explicação sobre uma solução mais permanente quando ela estiver pronta.

Mecanismo de transição

Ao registrar um beacon de anúncio, use a palavra-chave reserved.top_navigation, que adiciona automaticamente o cabeçalho Attribution-Reporting-Eligible para que o beacon possa ser registrado como uma origem de atribuição.

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

Para anexar dados no nível do evento ao beacon registrado, chame setReportEventDataForAutomaticBeacons() do 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 dele. 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 que será acionado durante o tempo de renderização do anúncio e o tempo de 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 do 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 de 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 tempo de conversão, você pode acionar a origem registrada durante o tempo de 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. 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 gatilho seja atribuído à fonte.

Agregação de dados da API Protected Audience

A API Private Aggregation é o mecanismo usado para gerar um relatório de resumo, que é um relatório agregado e ruidoso de dados coletados em intervalos. Um agrupamento é 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 diferente. Um relatório de resumo difere de um relatório de eventos porque não revela informações sobre cada evento individual. Com um relatório no nível do evento, você pode determinar que os usuários A, B e C viram a campanha 123. Com os relatórios resumidos, é possível medir o número de usuários que viram a campanha 123, e ruído é adicionado para proteger a privacidade do usuário.

Consulte o artigo Private Aggregation para mais informações sobre a API.

Agregação de indicadores de leilão

É possível agregar os indicadores disponíveis em worklets ao seu servidor usando a agregação privada. Para 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 nos worklets de relatórios do comprador/vendedor.

Neste exemplo, o lance vencedor é agregado ao bucket do proprietário 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 de evento e não são acionados por um evento fora do leilão. Para saber mais sobre como informar indicadores de leilão, consulte a explicação.

Agregação de 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 criando um agrupamento que represente essa campanha e o evento de clique. No frame do anúncio, é possível especificar qual evento ocorreu, mas não anexar um payload no nível do evento.

Para agregar indicadores de leilão por eventos, use privateAggregation.contributeToHistogramOnEvent(eventType, contribution), que recebe uma string especificando o tipo de evento e a contribuição a ser informada quando esse evento é acionado. Você pode chamar o método com um tipo de evento personalizado e, em seguida, chamar window.fence.reportEvent(eventType) do frame do anúncio para acionar o envio do relatório.

Imagine que você queira medir 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 agrupamento como a combinação do ID da campanha e do evento de clique e aumentar o valor desse agrupamento em 1 sempre que o evento for acionado.

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

Depois, no frame do anúncio, você pode acionar o envio do relatório chamando reportEvent(eventType):

Saiba mais sobre como acionar contribuições de agregação privada de um frame no explainer.

Relatórios de performance e resultados do leilão

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

A agregação privada fornece uma lista de valores de base para calcular o agrupamento e o valor da sua contribuição. Os valores de base disponíveis para os resultados do leilão são o valor do lance do anúncio vencedor, o valor do lance que foi classificado como o segundo mais alto e o motivo pelo qual um lance foi rejeitado do leilão.

Quando um valor de base é fornecido, como o valor do lance vencedor, é possível definir quanto adicionar ou subtrair desse valor e informar o valor final. Por exemplo, se o lance vencedor de R $5 for fornecido como o valor de base, subtraia seu lance de R $2 para calcular o valor real de R $3 de quanto você perdeu o leilão.

Relatórios de resultados do leilão

Vamos analisar um exemplo em que você perdeu um leilão e quer saber a diferença entre seu lance e o preço de compensação do leilão.

Para saber por quanto você perdeu o 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 é o baseValue dimensionado e deslocado 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 de confiança. Os vendedores podem coletar o tempo de geração de lances e o tempo de indicador de lance confiável de cada comprador com a permissão deles.

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 que é protegido com gates ao ler e processar os valores armazenados. Um dos portões disponíveis para a API Shared Storage é a Private Aggregation. Só é possível ler os valores no armazenamento compartilhado de dentro de um worklet, e você pode gerar relatórios sobre esses valores usando a agregação privada do worklet.

Também é possível gravar no armazenamento compartilhado usando worklets de lances, pontuação e relatórios da API Protected Audience. Depois, você pode informar esses valores no armazenamento compartilhado ao seu servidor usando a agregação privada . 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 chaves e valores no armazenamento compartilhado:

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

Depois, você pode carregar um worklet do 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 sobre o assunto no 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 (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.