Cómo realizar la integración con B&A como comprador

Los servicios de ofertas y subastas (B&A) son un conjunto de servicios para compradores y vendedores de anuncios que se ejecutan en un entorno de ejecución confiable (TEE) para facilitar una subasta de Protected Audience (PA). En esta guía para desarrolladores, se explica cómo un comprador puede realizar la integración con una subasta de PA de B&A para Chrome.

Descripción general

Para participar en una subasta de Protected Audience con los servicios de B&A, el comprador actualiza el grupo de interés (GI) para optimizar la carga útil y mejorar la latencia de la subasta.

El comprador requiere las siguientes tareas de optimización de la carga útil:

Grupo de interés para B&A

El siguiente es un ejemplo de configuración de grupo de intereses para una subasta de PA de B&A con la optimización de la carga útil 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,
});

Las diferencias entre la configuración de B&A y la configuración de grupos de intereses integrados en el dispositivo son las siguientes:

Campos IG de B&A IG integrado en el dispositivo Se incluye en la carga útil de la subasta de B&A
auctionServerRequestFlags Usado No utilizado No
userBiddingSignals No se recomienda Usado No, si se establece la marca omit-user-bidding-signals
adRenderId en ads y adComponents Usado No utilizado Si se establece la marca omit-ads, adRenderId en ads solo está disponible en browserSignals.prevWins de la carga útil. adRenderId definido en adComponents no se incluye en la carga útil.

Si no se establece la marca omit-ads, está disponible en browserSignals.prevWins, interestGroup.adRenderIds y interestGroup.adComponentRenderIds.

renderURL en ads y adComponents Usado Usado No
metadata en ads y adComponents No utilizado Usado No
IDs de informes en ads Usado Usado No
  • El campo auctionServerRequestFlags permite establecer marcas que le indican al navegador que omita algunos datos en la carga útil de la subasta de B&A.
  • El valor userBiddingSignals se puede definir en el grupo de intereses, pero se recomienda omitirlos con la marca omit-user-bidding-signals. Los indicadores omitidos se pueden proporcionar con el servicio K/V.
  • El campo adRenderId se establece junto con el renderURL asociado, pero solo adRenderId se convertirá en parte de la carga útil de la subasta de B&A. La URL de renderización que se muestra desde generateBid() más adelante durante el tiempo de subasta debe coincidir con la URL de renderización definida en el IG.
  • Los IDs de informes se definen en el IG de B&A, pero no se incluyen en la carga útil de la subasta de B&A. El ID de informe que se muestra desde generateBid() más adelante durante el tiempo de subasta debe coincidir con la URL de renderización definida en el IG.
  • Los IDs de ad.metadata y de informes no se incluyen en la carga útil de la subasta de B&A, sino que esos datos están disponibles a través del uso del servicio de par clave-valor de confianza.

Ten en cuenta que los renderURL y los IDs de informes en ads aún se definen en la configuración del grupo de intereses, aunque no se incluyen en la carga útil de la solicitud de subasta, ya que el navegador verifica que la URL de renderización y los IDs de informes que se muestran de la función generateBid() del servicio de ofertas coincidan con los valores definidos en el grupo de intereses.

joinAdInterestGroup() tareas

Se deben realizar las siguientes tareas para la llamada a joinAdInterestGroup().

Cómo configurar marcas de solicitud del servidor

El campo auctionServerRequestFlags de la configuración de joinAdInterestGroup() acepta las siguientes marcas:

Flag Descripción
omit-user-bidding-signals La marca omit-user-bidding-signals omite el objeto userBiddingSignals en la carga útil de la subasta.

Si no se establece la marca, el valor de userBiddingSignals definido en el grupo de intereses estará disponible en generateBid() del servicio de ofertas.

omit-ads La marca omit-ads le indica al navegador que omita los objetos ads y adComponents en la carga útil de la subasta.

El adRenderId estará disponible en la propiedad prevWins de browserSignals.

Si no se establece la marca, los campos adRenderIds y adComponentRenderIds en el argumento interestGroup de generateBid() contendrán los IDs de renderización de anuncios correspondientes.

Se recomienda que los compradores elijan la marca omit-ads. En algún momento en el futuro, es posible que pasar IDs de renderización y IDs de renderización de componentes de anuncios desde el cliente deje de estar disponible para optimizar aún más la carga útil.

Para controlar los datos omitidos, se pone a disposición la información relevante en trustedBiddingSignals. Las marcas se pueden usar de forma individual y no es necesario que se usen en conjunto.

Ejemplo de uso:

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

Establece los IDs de renderización de anuncios

Para reducir el tamaño de la carga útil de la subasta de B&A, se omiten los objetos ads y adComponents del grupo de intereses y, a su vez, estos objetos no están disponibles dentro de la función generateBid() que se ejecuta en el servicio de ofertas.

Para controlar la información del anuncio que falta, el comprador mantiene un identificador (adRenderId y adComponentRenderId) asociado con cada anuncio en la configuración del grupo de intereses. El identificador debe ser una DOMString de 12 bytes o menos. Si el identificador está codificado en Base64, su longitud debe ser de 12 bytes o menos.

Ejemplo de un grupo de intereses con IDs de renderización de anuncios:

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

Los adRenderId asociados con los anuncios estarán disponibles en prevWins.browserSignals en generateBid().

Aunque renderURL no se incluye en la carga útil de la solicitud, la URL de renderización que se muestra de generateBid() debe coincidir con la URL de renderización definida en la configuración del grupo de intereses. Las tecnologías publicitarias pueden enviar metadatos del anuncio y otra información en trustedBiddingSignals para que se puedan generar la URL de renderización del anuncio y la URL de renderización del componente del anuncio para la oferta durante la ejecución de generateBid().

Establece prioridades de los grupos de intereses

Chrome permite que los compradores prioricen los grupos de intereses. Si se alcanza el límite de tamaño de la carga útil por comprador establecido por el vendedor, los valores de prioridad del grupo de intereses se usan para descartar los grupos de intereses de prioridad más baja de un solo comprador cuando se genera la carga útil de la subasta de B&A para el vendedor. Para seleccionar grupos de intereses entre diferentes compradores, el navegador toma la decisión en función del tamaño de la carga útil serializada. De forma predeterminada, cada comprador tiene el mismo tamaño. Ten en cuenta que la priorización real se produce en los servidores de B&A, y no cuando se genera la carga útil de la solicitud.

La prioridad se calcula en el momento de la subasta con los vectores de prioridad del comprador (priorityVector) y los indicadores de prioridad del vendedor (prioritySignals). El comprador puede anular los indicadores de prioridad del vendedor.

Propiedad Descripción
Vector de prioridad El comprador proporciona los vectores como el valor de la clave priorityVector del servicio de par clave-valor.
Indicadores de prioridad El vendedor proporciona los indicadores configurando priority_signals de la configuración de la subasta.
Anulaciones de indicadores de prioridad El comprador proporciona la anulación en el campo priority_signals_overrides de PerBuyerConfig en la configuración de la subasta.

Durante la subasta, el navegador calcula el producto escalar disperso de las claves coincidentes en priorityVector y prioritySignals para la prioridad. En el siguiente diagrama, la prioridad se calcula mediante (4 * 2) + (3 * -1), que se reduce a 8 + -3, por lo que la prioridad de este grupo de intereses en el momento de la subasta es 5.

Cada clave en el vector de prioridad y los objetos de indicadores de prioridad se multiplican entre sí y, luego, los resultados se suman para calcular la prioridad.
Figura 1: Cálculo de prioridad con los vectores del comprador y los indicadores del vendedor

También hay indicadores adicionales disponibles para establecer prioridades en B&A:

Indicador Descripción
deviceSignals.one El valor siempre es 1 y es útil para agregar una constante al producto punto.
deviceSignals.ageInMinutes El valor describe la antigüedad del grupo de intereses (el tiempo transcurrido desde la última incorporación al grupo de intereses) en minutos como un número entero entre 0 y 43,200.
deviceSignals.ageInMinutesMax60 El valor describe lo mismo que el indicador ageInMinutes, pero tiene un máximo de 60. Si el grupo tiene más de 1 hora, se muestra 60.
deviceSignals.ageInHoursMax24 El valor describe la antigüedad del grupo de interés en horas, con un máximo de 24 horas. Si el grupo tiene más de un día, se muestra 24.
deviceSignals.ageInDaysMax30 El valor describe la antigüedad del grupo de intereses en días, con un máximo de 30 días. Si el grupo tiene más de 30 días, se muestra 30.

Para obtener más información, visita la explicación en GitHub.

Configura indicadores de ofertas confiables

Dado que se omitirán algunos datos de la carga útil de la subasta de B&A, puedes usar el servicio de par clave-valor para proporcionar los datos omitidos como indicadores de ofertas de confianza a la función generateBid().

El servicio de K/V puede proporcionar los siguientes datos omitidos:

  • userBiddingSignals si lo usa el comprador
  • metadata asociado con cada anuncio
  • adRenderId asociado con cada anuncio
  • ID de informes
Los datos omitidos del grupo de intereses se pueden enviar al servidor de recopilación del comprador. El servidor de la colección envía los datos al servicio de par clave-valor y, más adelante, el navegador carga esos datos desde el servicio de par clave-valor.
Figura 2: Ejemplo de configuración de indicadores de confianza

Un enfoque que se puede adoptar es incluir un identificador único en las claves de los indicadores de ofertas de confianza y, luego, enviar los datos asociados a tu servidor para que se carguen en el servicio de par clave-valor. Sin embargo, la implementación real depende de la tecnología publicitaria, y la API no es prescriptiva.

En el siguiente ejemplo, se describe un enfoque que se puede implementar:

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

En el ejemplo, se define un identificador único para un IG y se convierte en parte de la clave de indicadores de confianza. La clave del IG y sus valores asociados se envían a tu servidor para que se cargue en el servicio de par clave-valor. Más adelante durante la subasta, el navegador recupera los indicadores de confianza y los pone a disposición en la función generateBid() del comprador.

Devuelve el indicador de actualización del grupo de intereses de K/V si es necesario

La clave updateIfOlderThanMs de los indicadores de confianza se usa para actualizar el grupo de intereses antes del intervalo diario habitual. Si el grupo de intereses no se unió ni se actualizó durante un período que supera el valor de milisegundos que se muestra para la clave updateIfOlderThanMs, el grupo de intereses se actualizará con el mecanismo updateURL. Ten en cuenta que Chrome no actualizará los grupos de intereses con más frecuencia que una vez cada 10 minutos.

Si la subasta de B&A muestra un anuncio ganador que no coincide con uno de los anuncios definidos en el grupo de intereses almacenado en el navegador, este no aprobará la subasta. El mecanismo updateIfOlderThanMs puede ser útil para garantizar que el navegador y la subasta de B&A estén de acuerdo con el conjunto de anuncios del grupo de interés.

Visita la explicación para obtener más información.

generateBid() tareas

Se deben realizar las siguientes tareas para la llamada a generateBid().

Lee los indicadores del navegador

El objeto browserSignals que se pasa a la llamada generateBid() de B&A se ve de la siguiente manera:

{
  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,
}

Las siguientes propiedades modificadas o nuevas están disponibles en browserSignals:

Propiedad Descripción
prevWins prevWins es un array de tuplas de tiempo y anuncio. El tiempo representa los segundos transcurridos desde la victoria anterior del anuncio asociado en los últimos 30 días.

Se modificó para proporcionar adRenderId en lugar del objeto ad.

wasmHelper Es el objeto compilado del código proporcionado desde biddingWasmHelperURL.
dataVersion De manera opcional, un servidor de confianza puede incluir un encabezado de respuesta Data-Version numérico que estará disponible en generateBid().

Lee la explicación en GitHub para obtener más información.

Cómo mostrar la URL de renderización de generateBid()

Dado que se omite el objeto ads en la carga útil de la subasta de B&A, se debe volver a crear la URL de renderización que se muestra desde generateBid(). Tu implementación determina cómo se vuelve a crear la URL de renderización, y la URL que se muestra debe coincidir con la URL de renderización definida en el grupo de intereses.

Un enfoque que se podría adoptar es mantener una URL base y completar la plantilla con la información de interestGroup y trustedBiddingSignals.

En este ejemplo, definimos 4 anuncios en función del color y el producto:

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
  ]
})

Luego, enviamos el color favorito del usuario y la información del producto para que se cargue en el servicio de par clave-valor:

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

Más adelante, cuando se ejecute la subasta, los indicadores de ofertas de confianza estarán disponibles en generateBid(), y esa información se puede usar para reconstruir la URL:

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

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

Cómo mostrar los IDs de informes de generateBid()

Dado que los IDs de informes no se incluyen en la carga útil de la subasta de B&A, el ID estará disponible para generateBid() a través de indicadores de ofertas confiables. Una vez que se determina qué ID de informe se debe usar, se muestra el ID de informe elegido desde generateBid(). Los IDs que se muestran deben coincidir con los que se definieron en el grupo de intereses.

En este ejemplo, se elige el anuncio 1 y se muestra su ID de renderización asociado desde generateBid():

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

El ID de informe que se muestra estará disponible en reportWin() a través de buyerReportingSignals:

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

Si no se muestra buyerReportingId desde generateBid(), el valor interestGroupName estará disponible en buyerReportingSignals en lugar de buyerReportingId.

Visita la guía de ID de informes para obtener más información.

Próximos pasos

Los siguientes recursos están disponibles para ti

Más información

¿Tienes alguna pregunta?