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 que são executados em um ambiente de execução confiável (TEE) para facilitar um leilão da Protected Audience (PA). Este guia para desenvolvedores explica como um comprador pode fazer a integração com um leilão de PA da B&A para 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 (GI) para otimizar o payload e melhorar a latência do leilão.

As seguintes tarefas de otimização de payload são necessárias para o comprador:

• joinAdInterestGroup() tarefas
  • Definir flags de solicitação do servidor
  • Definir IDs de renderização de anúncios
  • Definir prioridades de grupo de interesse
  • Configurar indicadores de lances confiáveis
• generateBid() tarefas
  • Ler indicadores do navegador
  • Retornar URL de renderização
  • ID do relatório de devolução

Grupo de interesse para B&A

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 de grupo de interesse no dispositivo e de B&A são:

• O campo auctionServerRequestFlags permite definir flags que informam ao navegador para omitir alguns dados na carga útil do leilão de B&A.
• O valor userBiddingSignals pode ser definido no grupo de interesse, mas é recomendável omiti-los 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 fará 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 do B&A, mas não estão incluídos na carga útil do leilão do B&A. O ID de relatórios retornado de generateBid() mais tarde durante o tempo do leilão precisa corresponder ao URL de renderização definido no IG.
• Os IDs de relatório e ad.metadata não estão incluídos na carga útil do leilão da B&A. Em vez disso, esses dados ficam disponíveis com o 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 na carga útil da solicitação de leilão. Isso acontece 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 seguintes tarefas precisam ser realizadas para a chamada joinAdInterestGroup().

Definir flags de solicitação do servidor

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

Os dados omitidos são tratados disponibilizando informações relevantes em trustedBiddingSignals. Elas podem ser usadas individualmente ou 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 da carga útil do leilão de B&A, os objetos ads e adComponents do grupo de interesse são omitidos. Assim, esses objetos não ficam disponíveis na função generateBid() em execução no serviço de lances.

Para lidar com as informações de anúncio 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 uma DOMString com 12 bytes ou menos. Se o identificador for codificado em Base64, ele precisará ter 12 bytes ou menos.

Exemplo de um 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'
    },
  ],
});

Os adRenderId associados aos anúncios ficam disponíveis no prevWins.browserSignals em generateBid().

Embora o renderURL não esteja 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 sejam gerados para o lance durante a execução de generateBid().

Definir prioridades de grupo de interesse

O Chrome permite que os compradores priorizem grupos de interesse. Se o limite de tamanho de payload por comprador definido pelo vendedor for atingido, os valores de prioridade do grupo de interesse serão usados para descartar os grupos de interesse de menor prioridade para um único comprador quando o payload do leilão de B&A for gerado para o vendedor. Para selecionar grupos de interesse entre diferentes compradores, o navegador decide com base no tamanho do payload serializado. Por padrão, cada comprador recebe um tamanho igual. A priorização real ocorre nos servidores do 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.

Durante o leilão, o navegador calcula o produto escalar esparso 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.

Outros indicadores também podem ser usados para priorização na B&A:

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

Configurar indicadores de lances confiáveis

Como alguns dados serão omitidos da carga útil do leilão do B&A, use o serviço de chave/valor para fornecer os dados omitidos como indicadores de lances confiáveis à função generateBid().

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

• userBiddingSignals se usado pelo comprador
• metadata associados a cada anúncio
• adRenderId associados a cada anúncio
• Código do relatório

Uma abordagem possível é incluir um identificador exclusivo nas chaves de indicadores de lances confiáveis e enviar os dados associados ao seu servidor para que 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 grupo de interesse e passa a fazer parte da chave de indicadores de confiança. A chave do IG e os valores associados são enviados ao seu servidor para serem carregados no serviço de chave-valor. Em um momento posterior durante o leilão, o navegador busca os indicadores de confiança e os disponibiliza na função generateBid() do comprador.

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

A chave updateIfOlderThanMs para os indicadores de confiança é 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 superior ao valor de milissegundos retornado para a chave updateIfOlderThanMs, ele será atualizado com o mecanismo updateURL. O Chrome não atualiza os grupos de interesse mais do que uma vez a cada 10 minutos.

Se o leilão de B&A retornar um anúncio vencedor que não corresponda a um dos anúncios definidos no grupo de interesse armazenado no navegador, o navegador vai falhar no leilão. 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 a explicação para saber mais.

generateBid() tarefas

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

Ler indicadores do navegador

O objeto browserSignals transmitido para a chamada generateBid() da 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:

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

Como o objeto ads é omitido na carga útil 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, definimos 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 executado, 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 do B&A, o ID fica disponível para generateBid() por indicadores de lances confiáveis. Depois que o ID de relatório a ser usado é determinado, o ID escolhido é retornado de generateBid(). Os IDs retornados precisam corresponder aos 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órios retornado fica disponível em reportWin() por 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 de IDs de relatórios para saber mais.

Próximas etapas

Os seguintes recursos estão disponíveis para você

Saiba mais

• Saiba mais sobre as configurações de leilão de B&A no Chrome.
• Teste a API Protected Audience com a B&A seguindo o codelab de testes locais de ponta a ponta.

Dúvidas?

• Se você tiver uma dúvida sobre os serviços de lances e leilões, abra um problema no repositório de serviços de lances e leilões.