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 (IG) 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:

• joinAdInterestGroup() tareas
  • Cómo establecer marcas de solicitud del servidor
  • Cómo establecer IDs de renderización de anuncios
  • Cómo establecer prioridades de grupos de interés
  • Configura indicadores de ofertas confiables
• generateBid() tareas
  • Leer indicadores del navegador
  • URL de devolución de la renderización
  • ID de informes de devoluciones

Grupo de interés para las ofertas y subastas

A continuación, se muestra un ejemplo de configuración de un grupo de interés 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 interés en el dispositivo son las siguientes:

• 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 de userBiddingSignals se puede definir en el grupo de interés, pero se recomienda omitirlo con la marca omit-user-bidding-signals. Los indicadores omitidos se pueden proporcionar con el servicio de K/V.
• El campo adRenderId se configura junto con el renderURL asociado, pero solo el adRenderId formará parte de la carga útil de la subasta de B&A. La URL de renderización que se devuelve desde generateBid() más adelante durante el tiempo de la subasta debe coincidir con la URL de renderización definida en el IG.
• Los IDs de informes se definen en la IG de B&A, pero no se incluyen en la carga útil de la subasta de B&A. El ID de informes que se devuelve desde generateBid() más adelante durante el tiempo de la 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 pares 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 interés, 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 devuelve la función generateBid() del servicio de ofertas coincidan con los valores definidos en el grupo de interés.

joinAdInterestGroup() tareas

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

Cómo configurar marcas de solicitudes del servidor

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

Los datos omitidos se manejan poniendo a disposición la información pertinente en trustedBiddingSignals. Las marcas se pueden usar de forma individual y no es necesario que se usen juntas.

Ejemplo de uso:

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

Establece 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 interés, 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 falta de información del anuncio, el comprador mantiene un identificador (adRenderId y adComponentRenderId) asociado a cada anuncio en la configuración del grupo de interés. El identificador debe ser un 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 interés 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().

Si bien renderURL no se incluye en la carga útil de la solicitud, la URL de renderización que se muestra desde generateBid() debe coincidir con la URL de renderización definida en la configuración del grupo de interés. Las tecnologías publicitarias pueden enviar metadatos del anuncio y otra información en trustedBiddingSignals, de modo 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().

Cómo establecer prioridades de grupos de interés

Chrome permite que los compradores prioricen los grupos de interés. Si se alcanza el límite de tamaño de la carga útil por comprador establecido por el vendedor, se usarán los valores de prioridad del grupo de interés para descartar los grupos de interés de menor prioridad para un solo comprador cuando se genere la carga útil de la subasta de B&A para el vendedor. Para seleccionar grupos de interés 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.

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 con (4 * 2) + (3 * -1), que se reduce a 8 + -3, por lo que la prioridad de este grupo de interés en el momento de la subasta es 5.

También hay indicadores adicionales disponibles para la priorización en B&A:

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

Configura indicadores de ofertas confiables

Dado que algunos datos se omitirán de la carga útil de la subasta de B&A, puedes usar el servicio de 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 el comprador lo usó
• metadata asociado a cada anuncio
• adRenderId asociado a cada anuncio
• ID de informes

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 puedan cargar en el servicio de 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 los indicadores de confianza. La clave del IG y sus valores asociados se envían a tu servidor para que se carguen en el servicio de pares 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 interés del almacén de clave-valor si es necesario.

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

Si la subasta de B&A devuelve un anuncio ganador que no coincide con uno de los anuncios definidos en el grupo de interés almacenado en el navegador, este último fallará la subasta. El mecanismo updateIfOlderThanMs puede ser útil para garantizar que el navegador y la subasta de B&A coincidan en 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 de generateBid().

Leer los indicadores del navegador

El objeto browserSignals que se pasa a la llamada de 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 nuevas o modificadas están disponibles en browserSignals:

Devuelve la URL de renderización de generateBid()

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

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 según el 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 carguen en el servicio de 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 podrá 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`
  }
}

Devuelve 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 está disponible para generateBid() a través de indicadores de ofertas confiables. Una vez que se determina qué ID de informes se debe usar, el ID de informes elegido se devuelve desde generateBid(). Los IDs devueltos deben coincidir con los IDs definidos en el grupo de interés.

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

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

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

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

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

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

Próximos pasos

Los siguientes recursos están disponibles para ti

Más información

• Obtén más información sobre la configuración de la subasta de B&A en Chrome
• Experimenta con Protected Audience con B&A siguiendo el codelab de pruebas locales de extremo a extremo.

¿Tienes alguna pregunta?

• Si tienes alguna pregunta sobre los servicios de ofertas y subastas, abre un problema en el repositorio de los servicios de ofertas y subastas.