Relatórios de leilão da API Protected Audience

bookmark_border Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Medir os 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 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:

• Agregação privada, que coleta indicadores e resultados de leilões para gerar relatórios de resumo.
• API Ads Reporting para frames restritos e iframes, que é um canal dentro dos 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 são um mecanismo de transição até que um mecanismo de relatórios mais reservado seja criado.
• Relatórios de atribuição, que permite associar dados de conversão a indicadores de leilão.
• Armazenamento compartilhado, que permite gravar indicadores de leilão em um armazenamento entre origens e gerar relatórios sobre esses dados 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 tempo 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 restrito ou um iframe no site do editor; e o tempo de conversão, quando o usuário realiza alguma ação no outro site que pode ser atribuída ao leilão.

Durante o leilão, é possível informar os dados do leilão usando worklets de relatórios. Durante a renderização, é possível informar dados de engajamento de um iframe ou um frame limitado. Durante a conversão, é possível informar 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 em 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 informar 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 gerar dados, como indicadores de leilão, dados de eventos 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 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 auction config é a principal fonte de dados fornecida para ficar disponível como indicadores nos 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 interesses 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 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 o preço do lance vencedor e o motivo da rejeição de lances.
• Dados de performance que contêm informações de latência, como o tempo que 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 estão disponíveis para serem informados.

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

Durante a conversão, quando um usuário realiza uma ação na página de cliques que é atribuída de volta 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ória no leilão no nível do evento vão continuar disponíveis, os frames restritos não serão necessários para renderizar um anúncio da Protected Audience e um iframe com acesso à rede sem restrições poderá ser usado para relatórios no nível do evento. Além disso, a API Ads Reporting está disponível em frames e iframes restritos para você associar dados de leilão e conversão a dados no nível do evento do frame. Isso foi projetado 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 de leilão 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 de 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 para a string de URL fornecida quando a renderização do anúncio começa. É possível codificar qualquer sinal disponível nos 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 chamado de reportResult() e um relatório de vitória para o comprador quando chamado de reportWin(). A função sendReportTo() vai estar disponível até pelo menos 2026.

Relatório de engajamento

Um relatório de engajamento contém dados de evento de um criativo de anúncio, como dados de impressões ou cliques associados aos indicadores do leilão da API Protected Audience que renderizou o anúncio. Como o anúncio é renderizado após o término do leilão, os indicadores do leilão não estão disponíveis no frame que renderiza o anúncio. Para associar esses dados de períodos diferentes, 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 protegido, já que um ID exclusivo não pode ser transmitido pelo incorporador porque a comunicação entre o incorporador e o frame protegido é limitada. Para associar dados de leilão a dados de eventos de um anúncio de frame restrito, use a API Ads Reporting.

API Ads Reporting para frames e iframes restritos

A API Ads Reporting para frames e iframes restritos 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 de relatórios com os indicadores adicionados como parâmetros de consulta. Você também especifica o evento personalizado que quer associar ao URL de relatórios. Depois, quando o anúncio for renderizado em um frame restrito, você poderá acionar o evento personalizado chamando a função window.fence.reportEvent(). Os dados disponíveis no frame cercado podem ser adicionados como o payload.

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

No exemplo abaixo, um ID de campanha é 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 até pelo menos 2026 pelos mesmos motivos que o relatório de vitórias.

Para saber mais, consulte o texto explicativo.

Acesso à rede sem restrições

Os frames delimitados permitem carregar 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 servidor mais tarde associando os dados de eventos de um período restrito com os 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á limitado 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 lá e você quer atribuir a compra ao anúncio que foi mostrado. A API Attribution Reporting será integrada à API Protected Audience para combinar os dados do leilão do site do editor e os dados de conversão do site do anunciante.

Enquanto desenvolvemos uma solução mais permanente, você pode usar a API Attribution Reporting para frames restritos 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 de anúncio. Vamos publicar um explicativo sobre 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, que vai adicionar automaticamente o cabeçalho Attribution-Reporting-Eligible para que o beacon se qualifique para ser registrado como uma origem 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() do frame protegido com o payload do evento.

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

Consulte a seção "Relatórios de atribuição" 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úncio 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 iframe ou do frame protegido 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 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 do 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 a conversão, você pode acionar a origem registrada no leilão.

Após o processo acima, o comprador terá um relatório de leilão, um relatório de engajamento e um relatório 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. O SSP também precisa estar presente na página de destino para que o gatilho seja atribuído à fonte.

Como agregar dados da API Protected Audience

A API Private Aggregation é o mecanismo usado para informar dados da Protected Audience e gerar um relatório de resumo, que é um relatório agregado e com ruídos dos dados coletados em intervalos. Um bucket é representado por uma chave de agregação, e algumas informações podem ser codificadas nela.

Por exemplo, um evento de impressão de anúncio pode ser contabilizado em diferentes buckets, em que cada bucket representa uma campanha de anúncios diferente. Um relatório de resumo é diferente 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 visualizaram a campanha 123. Com os relatórios de resumo, você pode medir o número de usuários que viram a campanha 123, e ruídos são adicionados para proteger a privacidade deles.

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

Como agregar indicadores de leilão

É possível agregar os indicadores 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 nos worklets de lances do comprador, de pontuação do vendedor e 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 eventos e não são acionados por um evento fora do leilão. Para saber mais sobre como informar indicadores de leilão, consulte o texto explicativo.

Como agregar indicadores de leilão com dados de eventos

É possível agregar sinais 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 bucket que representa essa campanha e o evento de clique. No frame do anúncio, é possível especificar o evento que ocorreu, mas não é possível 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 que especifica o tipo de evento e a contribuição a ser informada quando o evento for 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.

Digamos 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, é possível definir um bucket como a combinação do ID da campanha e do evento de clique e aumentar o valor desse bucket em 1 sempre que o evento for acionado.

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

Depois, no futuro, 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 texto explicativo.

Gerar relatórios sobre os resultados e a performance do leilão

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

A agregação privada fornece uma lista de valores de base que podem ser usados para calcular o bucket 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, você pode definir quanto adicionar ou subtrair desse valor e informar o valor final. Por exemplo, se o lance vencedor de US $5 for fornecido como o valor base, você poderá subtrair seu lance de US $2 para calcular o valor real de US $3 de quanto você perdeu o leilão.

Relatórios de resultados de leilões

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 liquidação do leilão.

Para saber quanto você perdeu o leilão, subtraia o preço do lance vencedor do seu lance:

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á o baseValue dimensionado deslocado pelo valor offset. Para saber mais, consulte o texto explicativo.

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 tempo de geração de lances e o tempo do indicador de lance confiável de cada comprador com a permissão deles.

Consulte o texto explicativo para saber mais.

Como armazenar indicadores de leilão no armazenamento compartilhado

O armazenamento compartilhado é um armazenamento não particionado e entre origens em que você pode gravar livremente, mas que é protegido por portas ao ler e processar os valores armazenados. Um dos portões 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 gerar relatórios sobre esses valores usando a agregação privada no worklet.

Também é possível gravar no armazenamento compartilhado de worklets de lances, pontuação e relatórios da API Protected Audience. Mais tarde, você poderá informar 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 Seleção de URL.

Em um worklet da API Protected Audience, é possível gravar qualquer chave e valor no armazenamento compartilhado:

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

Mais tarde, você pode carregar um worklet de armazenamento compartilhado para ler e enviar esse valor com a agregação particular:

// 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 "Armazenamento compartilhado" do guia para desenvolvedores da API Protected Audience, explicação, 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.