Integrar com a B&A como comprador

Os serviços de lances e leilões (B&A) são um conjunto de serviços para compradores e vendedores de anúncios executados em um ambiente de execução confiável (TEE) para facilitar um leilão de público-alvo protegido (PA). Este guia para desenvolvedores explica como um comprador pode fazer a integração com um leilão de PA de B&A para o Chrome.

Visão geral

Para participar de um leilão da Protected Audience com os serviços de B&A, o comprador atualiza o grupo de interesse (IG) para otimizar o payload e melhorar a latência do leilão.

As seguintes tarefas de otimização de payload são exigidas pelo comprador:

Grupo de interesse para perguntas e respostas

Confira a seguir um exemplo de configuração de grupo de interesse para um leilão de PA de B&A com otimização de payload aplicada:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

As diferenças entre as configurações do grupo de interesse no dispositivo e do B&A são as seguintes:

Campos Perguntas e respostas do Instagram IG no dispositivo Incluído no payload do leilão de B&A
auctionServerRequestFlags Usados Não utilizado Não
userBiddingSignals Não recomendado Usados Não, se a flag omit-user-bidding-signals estiver definida
adRenderId em ads e adComponents Usados Não utilizado Se a flag omit-ads estiver definida, o adRenderId em ads estará disponível apenas em browserSignals.prevWins do payload. O adRenderId definido em adComponents não é incluído no payload.

Se a flag omit-ads não estiver definida, ela estará disponível em browserSignals.prevWins, interestGroup.adRenderIds e interestGroup.adComponentRenderIds.
renderURL em ads e adComponents Usados Usados Não
metadata em ads e adComponents Não utilizado Usados Não
IDs de relatórios em ads Usados Usados Não
  • O campo auctionServerRequestFlags permite definir flags que informam ao navegador para omitir alguns dados na carga de dados do leilão de B&A.
  • O valor userBiddingSignals pode ser definido no grupo de interesse, mas é recomendável omitir esse valor usando a flag omit-user-bidding-signals. Os indicadores omitidos podem ser fornecidos usando o serviço K/V.
  • O campo adRenderId é definido com o renderURL associado, mas apenas o adRenderId vai fazer parte do payload do leilão de B&A. O URL de renderização retornado de generateBid() mais tarde durante o leilão precisa corresponder ao URL de renderização definido no IG.
  • Os IDs de relatórios são definidos no IG de B&A, mas não são incluídos no payload do leilão de B&A. O ID de relatório retornado de generateBid() mais tarde durante o leilão precisa corresponder ao URL de renderização definido no IG.
  • O ad.metadata e os IDs de relatórios não são incluídos no payload do leilão de B&A. Em vez disso, esses dados ficam disponíveis pelo uso do serviço de chave-valor confiável.

Os renderURLs e os IDs de relatórios em ads ainda são definidos na configuração do grupo de interesse, mas não são incluídos no payload da solicitação de leilão porque o navegador verifica se o URL de renderização e os IDs de relatórios retornados da função generateBid() do serviço de lances correspondem aos valores definidos no grupo de interesse.

joinAdInterestGroup() tarefas

As tarefas a seguir precisam ser realizadas para a chamada joinAdInterestGroup().

Definir sinalizações de solicitação do servidor

O campo auctionServerRequestFlags da configuração joinAdInterestGroup() aceita as seguintes flags:

Sinalização Descrição
omit-user-bidding-signals A flag omit-user-bidding-signals omite o objeto userBiddingSignals no payload do leilão.

Se a flag não estiver definida, o valor userBiddingSignals definido no grupo de interesse vai ficar disponível em generateBid() do serviço de lances.
omit-ads A flag omit-ads informa ao navegador para omitir os objetos ads e adComponents no payload do leilão.

O adRenderId vai estar disponível na propriedade prevWins de browserSignals.

Se a flag não estiver definida, os campos adRenderIds e adComponentRenderIds no argumento interestGroup de generateBid() vão conter os IDs de renderização de anúncios correspondentes.

É altamente recomendável que os compradores escolham a flag omit-ads. Em algum momento no futuro, a transmissão de IDs de renderização e IDs de renderização de componentes de anúncios do cliente poderá ser descontinuada para otimização de payload.

Os dados omitidos são processados disponibilizando informações relevantes em trustedBiddingSignals. As flags podem ser usadas individualmente e não precisam ser usadas juntas.

Exemplo de uso:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

Definir IDs de renderização de anúncios

Para reduzir o tamanho do payload do leilão de B&A, os objetos ads e adComponents do grupo de interesse são omitidos e, por sua vez, não estão disponíveis na função generateBid() executada no serviço de lances.

Para lidar com as informações de anúncios ausentes, o comprador mantém um identificador (adRenderId e adComponentRenderId) associado a cada anúncio na configuração do grupo de interesse. O identificador precisa ser um DOMString de 12 bytes ou menos. Se o identificador for codificado em Base64, o comprimento dele precisa ser de 12 bytes ou menos.

Exemplo de grupo de interesse com IDs de renderização de anúncios:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

O adRenderId associado aos anúncios vai ficar disponível em prevWins.browserSignals em generateBid().

Embora o renderURL não seja incluído no payload da solicitação, o URL de renderização retornado de generateBid() precisa corresponder ao URL de renderização definido na configuração do grupo de interesse. As adtechs podem enviar metadados de anúncios e outras informações em trustedBiddingSignals para que o URL de renderização do anúncio e o URL de renderização do componente do anúncio possam ser gerados para o lance durante a execução de generateBid().

Definir prioridades de grupos de interesse

O Chrome permite que os compradores priorizem grupos de interesse. Se o limite de tamanho do payload por comprador definido pelo vendedor for alcançado, os valores de prioridade do grupo de interesse serão usados para excluir os grupos de interesse de menor prioridade de um único comprador quando o payload do leilão de B&A for gerado para o vendedor. Para selecionar grupos de interesse entre compradores diferentes, o navegador decide com base no tamanho do payload serializado. Por padrão, cada comprador tem o mesmo tamanho. A priorização real ocorre nos servidores de B&A, e não quando o payload da solicitação é gerado.

A prioridade é calculada no momento do leilão usando os vetores de prioridade do comprador (priorityVector) e os indicadores de prioridade do vendedor (prioritySignals). O comprador pode substituir os indicadores de prioridade do vendedor.

Propriedade Descrição
Vetor de prioridade O comprador fornece os vetores como o valor da chave priorityVector do serviço de chave-valor.
Indicadores de prioridade O vendedor fornece os indicadores definindo priority_signals da configuração do leilão.
Modificações de indicadores prioritários O comprador fornece a substituição no campo priority_signals_overrides do PerBuyerConfig na configuração do leilão.

Durante o leilão, o navegador calcula o produto escalar das chaves correspondentes em priorityVector e prioritySignals para a prioridade. No diagrama a seguir, a prioridade é calculada por (4 * 2) + (3 * -1), que é reduzida para 8 + -3. Portanto, a prioridade desse grupo de interesse no momento do leilão é 5.

Cada chave nos objetos de vetor e indicadores de prioridade é multiplicada uma pela outra. Em seguida, os resultados são somados para calcular a prioridade.
Figura 1: cálculo de prioridade usando os vetores do comprador e os indicadores do vendedor

Outros indicadores também estão disponíveis para priorização em perguntas e respostas:

Sinal Descrição
deviceSignals.one O valor é sempre 1 e é útil para adicionar uma constante ao produto escalar.
deviceSignals.ageInMinutes O valor descreve a idade do grupo de interesse (o tempo desde a adesão mais recente) em minutos como um número inteiro entre 0 e 43.200.
deviceSignals.ageInMinutesMax60 O valor descreve o mesmo que o indicador ageInMinutes, mas tem o limite máximo de 60. Se o grupo tiver mais de uma hora, o valor retornado será 60.
deviceSignals.ageInHoursMax24 O valor descreve a idade do grupo de interesse em horas, com um máximo de 24 horas. Se o grupo tiver mais de um dia, o valor 24 será retornado.
deviceSignals.ageInDaysMax30 O valor descreve a idade do grupo de interesse em dias, com um máximo de 30 dias. Se o grupo tiver mais de 30 dias, o valor 30 será retornado.

Para saber mais, acesse a explicação no GitHub.

Configurar indicadores de lances confiáveis

Como alguns dados serão omitidos do payload do leilão de B&A, use o serviço de chave-valor para fornecer os dados omitidos como indicadores de lances confiáveis para a função generateBid().

Os seguintes dados omitidos podem ser fornecidos pelo serviço de K/V:

  • userBiddingSignals se usado pelo comprador
  • metadata associado a cada anúncio
  • adRenderId associado a cada anúncio
  • Código do relatório
Os dados omitidos do grupo de interesse podem ser enviados ao servidor de coleta do comprador. O servidor de coleta envia os dados para o serviço de chave-valor e, mais tarde, o navegador carrega esses dados do serviço de chave-valor.
Figura 2: exemplo de configuração de indicadores confiáveis

Uma abordagem possível é incluir um identificador exclusivo nas chaves de indicadores de lances confiáveis e enviar os dados associados ao servidor para que eles possam ser carregados no serviço de chave/valor. No entanto, a implementação real depende da adtech, e a API não é prescritiva.

O exemplo a seguir descreve uma abordagem que pode ser implementada:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

No exemplo, um identificador exclusivo é definido para um IG e passa a fazer parte da chave de indicadores confiáveis. A chave do IG e os valores associados são enviados ao servidor para serem carregados no serviço de chave-valor. Mais tarde, durante o leilão, o navegador busca os indicadores confiáveis e os disponibiliza na função generateBid() do comprador.

Se necessário, retorne o indicador de atualização do grupo de interesse do K/V

A chave updateIfOlderThanMs para os indicadores confiáveis é usada para atualizar o grupo de interesse antes do intervalo diário normal. Se o grupo de interesse não tiver sido adicionado ou atualizado em um período que exceda o valor de milissegundos retornado para a chave updateIfOlderThanMs, ele será atualizado com o mecanismo updateURL. O Chrome não atualiza os grupos de interesse com mais frequência do que uma vez a cada 10 minutos.

Se o leilão de B&A retornar um anúncio vencedor que não corresponde a um dos anúncios definidos no grupo de interesse armazenado no navegador, o leilão será cancelado. O mecanismo updateIfOlderThanMs pode ser útil para garantir que o navegador e o leilão de B&A concordem com o conjunto de anúncios no grupo de interesse.

Acesse o texto explicativo para saber mais.

generateBid() tarefas

As tarefas a seguir precisam ser realizadas para a chamada generateBid().

Ler sinais do navegador

O objeto browserSignals transmitido para a chamada generateBid() de B&A tem esta aparência:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

As seguintes propriedades modificadas ou novas estão disponíveis em browserSignals:

Propriedade Descrição
prevWins prevWins é uma matriz de tuplas de tempo e anúncio. O tempo representa os segundos decorridos desde a vitória anterior do anúncio associado nos últimos 30 dias.

Ele foi modificado para fornecer o adRenderId em vez do objeto ad.
wasmHelper Objeto compilado do código fornecido por biddingWasmHelperURL.
dataVersion Um servidor confiável pode incluir um cabeçalho de resposta Data-Version numérico que fica disponível em generateBid().

Leia a explicação no GitHub para saber mais.

Retornar o URL de renderização de generateBid()

Como o objeto ads é omitido no payload do leilão de B&A, o URL de renderização retornado de generateBid() precisa ser recriado. A forma como o URL de renderização é recriado é determinada pela sua implementação, e o URL retornado precisa corresponder ao URL de renderização definido no grupo de interesse.

Uma abordagem possível é manter um URL base e preencher o modelo com as informações de interestGroup e trustedBiddingSignals.

Neste exemplo, estamos definindo quatro anúncios com base na cor e no produto:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

Em seguida, enviamos a cor favorita do usuário e as informações do produto para serem carregadas no serviço de chave-valor:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

Mais tarde, quando o leilão for realizado, os indicadores de lances confiáveis vão ficar disponíveis em generateBid(), e essas informações poderão ser usadas para reconstruir o URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

Retornar IDs de relatórios de generateBid()

Como os IDs de relatórios não estão incluídos no payload do leilão de B&A, o ID fica disponível para generateBid() por meio de indicadores de lances confiáveis. Depois que o ID do relatório a ser usado é determinado, o ID escolhido é retornado de generateBid(). Os IDs retornados precisam corresponder aos IDs definidos no grupo de interesse.

Neste exemplo, o anúncio 1 é escolhido, e o ID de renderização associado a ele é retornado de generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

O ID de relatório retornado fica disponível em reportWin() até buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

Se buyerReportingId não for retornado de generateBid(), o valor interestGroupName estará disponível em buyerReportingSignals em vez de buyerReportingId.

Acesse o guia do ID de relatório para saber mais.

Próximas etapas

Os recursos a seguir estão disponíveis para você

Saiba mais

Dúvidas?