Se usó la API de Cloud Translation para traducir esta página.

Definir datos del público

Aprende a definir un público creando un grupo de interés con la API de Protected Audience. Lee la guía para desarrolladores para obtener información sobre el ciclo de vida completo de la API de Protected Audience y consulta la explicación de la API de Protected Audience para obtener una propuesta detallada de cómo los navegadores registran los grupos de intereses.

¿No eres desarrollador? Consulta la descripción general de la API de Protected Audience.

Grupos de intereses de la API de Protected Audience

Un grupo de interés de la API de Protected Audience representa a un grupo de personas con un interés común, que corresponde a una lista de remarketing. Cada grupo de interés de la API de Protected Audience tiene un propietario.

Los propietarios de grupos de interés actúan como compradores en la subasta de anuncios de la API de Protected Audience. La pertenencia a un grupo de interés se almacena en el navegador y en el dispositivo del usuario, y no se comparte con el proveedor del navegador ni con nadie más.

Funciones de API

`joinAdInterestGroup()`

La plataforma orientada a la demanda (DSP) del anunciante, o el propio anunciante, llaman a navigator.joinAdInterestGroup() para solicitar al navegador que agregue un grupo de interés a su lista de membresías.

El origen del contexto de llamada de joinAdInterestGroup() debe coincidir con el origen del propietario del grupo de interés, por lo que se deberá llamar a joinAdInterestGroup() desde un iframe (por ejemplo, desde una DSP), a menos que el origen del propietario del grupo de interés coincida con el origen del documento actual (por ejemplo, un sitio web con sus propios grupos de intereses).

joinAdInterestGroup() requiere permiso de:

El sitio que se visita
El propietario del grupo de interés

Esto significa que no es posible que malicious.example llame a joinAdInterestGroup() para un grupo de interés que pertenece a dsp.example.com sin que dsp.example.com otorgue permiso.

Permiso del sitio visitado

El permiso se puede otorgar desde el mismo origen o desde un origen cruzado. De forma predeterminada, se otorga permiso para las llamadas de joinAdInterestGroup() desde el mismo origen que el sitio visitado (es decir, desde el mismo origen que el marco de nivel superior de la página actual).

Ejemplo de uso

A continuación, te mostramos un ejemplo de cómo podrías definir un grupo de interés y pedirle al navegador que se una al grupo.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

El objeto interestGroup que se pasa a la función no debe tener más de 50 kiB; de lo contrario, la llamada fallará. El segundo parámetro especifica la duración del grupo de interés, con un límite de 30 días. Las llamadas sucesivas reemplazan los valores almacenados previamente.

Punto clave: Todas las URLs usadas como parámetros para los métodos de la API de Protected Audience deben provenir de orígenes seguros, es decir, todos los recursos deben entregarse a través de URLs HTTPS. En Cómo usar HTTPS para el desarrollo local, se explica cómo hacerlo cuando se ejecuta la API de Protected Audience de forma local. Además, biddingLogicUrl, decisionLogicUrl y trustedBiddingSignals requieren un encabezado de respuesta HTTP X-Allow-FLEDGE: true.

Propiedades obligatorias

Las únicas propiedades obligatorias para los grupos de interés son owner y name:

Propiedad	Ejemplo	Rol
`owner`	`https://dsp.example`	Origen del propietario del grupo de interés.
`name`	`custom-bikes`	Es el nombre del grupo de interés.

Propiedades opcionales

Las propiedades restantes son opcionales:

biddingLogicUrl^{1, 2}: Ejemplo: https://dsp.example/bid/custom-bikes/bid.js; Función: URL para las ofertas que se ejecuta JavaScript en el worklet.
biddingWasmHelperUrl^{1, 2}: Ejemplo: https://dsp.example/bid/custom-bikes/bid.wasm; Función: URL para el código de WebAssembly generado desde biddingLogicUrl.
updateUrl²: Ejemplo: https://dsp.example/bid/custom-bikes/update; Función: URL que muestra JSON para actualizar los atributos del grupo de interés. (consulta el artículo Cómo actualizar los datos del público y actualizar los anuncios).
trustedBiddingSignalsUrl²: Ejemplo: https://dsp.example/trusted/bidding-signals; Función: URL base para solicitudes de par clave-valor al servicio de par clave-valor de confianza del ofertante.
trustedBiddingSignalsKeys: Ejemplo: ['key1', 'key2' ...]; Función: Claves para solicitudes al servicio de par clave-valor de confianza.
userBiddingSignals: Ejemplo: {...}; Rol: Metadatos adicionales que el propietario puede usar durante las ofertas
ads¹: Ejemplo: [bikeAd1, bikeAd2, bikeAd3]; Rol: Anuncios que se podrían renderizar para este grupo de interés.
adComponents: Ejemplo: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Función: componentes para anuncios compuestos por varias partes.

¹ Las propiedades biddingLogicUrl y ads son opcionales, pero obligatorias para participar en una subasta. Puede haber casos de uso para crear un grupo de interés sin estas propiedades. Por ejemplo, el propietario de un grupo de interés podría agregar un navegador a un grupo de interés para una campaña que todavía no se está publicando o para otro uso futuro, o que se haya quedado sin presupuesto publicitario de forma temporal.

² En la implementación actual de la API de Protected Audience, biddingLogicUrl, biddingWasmHelperUrl, updateUrl y trustedBiddingSignalsUrl deben tener el mismo origen que el propietario. Es posible que no sea una restricción a largo plazo, y las URLs ads y adComponents no tienen tal restricción.

Cómo especificar anuncios para un grupo de interés

Los objetos ads y adComponents incluyen una URL para la creatividad de un anuncio y, opcionalmente, metadatos arbitrarios que se pueden usar en el momento de la licitación.

Por ejemplo:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

`leaveAdInterestGroup()`

El propietario del grupo de interés puede solicitar que se quite el navegador de un grupo de interés. El navegador quita el grupo de interés de su lista de membresía.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Si un usuario vuelve al sitio que le pidió al navegador que agregara un grupo de interés, el propietario del grupo de interés puede llamar a la función navigator.leaveAdInterestGroup() para solicitar al navegador que quite el grupo de interés.

El código de un anuncio también puede llamar a esta función para su grupo de interés.

Preguntas frecuentes

¿Cuál es la cantidad máxima de grupos de interés por propietario para un solo usuario?

Chrome permite hasta 1000 grupos de interés por propietario y hasta 1000 propietarios. Estos límites se diseñaron como barreras de seguridad, no deben alcanzarse en un funcionamiento normal.

¿Cómo puedo maximizar los anuncios basados en un grupo de interés que alcanzan los umbrales de k-anon?

Como señala la explicación pública, dado que un solo grupo de interés puede mostrar varios anuncios posibles, el grupo tendrá la oportunidad de volver a ofertar otro de sus anuncios para que actúe como "anuncio de resguardo" cada vez que su opción más preferida se encuentre por debajo del umbral. Esto significa que un anuncio pequeño y especializado que aún está por debajo del umbral de k-anonimato aún podría elegir participar en las subastas, y su grupo de interés tiene una forma de recurrir a un anuncio más genérico hasta que el más especializado tenga un público lo suficientemente grande.

Desde una perspectiva táctica, puedes considerar lo siguiente:

Para que un anuncio nuevo comience a publicarse, simplemente comience a ofertar con él en los casos en que desee que se muestre. No necesitas hacer nada más.
Puedes tener un anuncio de resguardo para usar cuando los anuncios nuevos no sean k-anon. Existe cierto riesgo de que tu anuncio de resguardo no sea k-anon, por lo que, a veces, podrías considerar simplemente ofertar con el anuncio de resguardo en primer lugar. Quizás hagas este 1% de las veces, por ejemplo, si ese es un buen nivel para asegurarte de que esperas que el resguardo se mantenga por encima del umbral.

Recientemente, se analizaron otras formas de funcionar, por lo que, si tienes algún caso de uso en el que este mecanismo podría causar problemas, sigue participando en la conversación pública sobre las formas en que podría mejorar la API.

Todas las referencias de la API de Protected Audience

Las guías de referencia de la API están disponibles:

Guía para desarrolladores sobre la API de Protected Audience
Guía para compradores de anuncios sobre los grupos de interés y la generación de ofertas de Protected Audience.
Guía para vendedores de anuncios sobre las subastas de anuncios de Protected Audience.
Guía para informar los resultados de las subastas
Prácticas recomendadas para la latencia de subasta de anuncios de Protected Audience
Cómo solucionar problemas de Protected Audience

La explicación de la API de Protected Audience también proporciona detalles sobre la compatibilidad y las restricciones de funciones.