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 ver 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 sobre cómo los navegadores registran los grupos de interés.

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

Grupos de interés 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 al 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 ninguna otra persona.

Funciones de API

`joinAdInterestGroup()`

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

El origen del contexto de llamada para 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 el permiso de:

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

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

Permiso del sitio visitado

Los permisos se pueden otorgar desde el mismo origen o origen cruzado. De forma predeterminada, se concede permiso a las llamadas de joinAdInterestGroup() que provengan del mismo origen que el sitio visitado (en otras palabras, del mismo origen que el marco de nivel superior de la página actual).

Ejemplo de uso

A continuación, se muestra un ejemplo de cómo se puede 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 superar los 50 kiB de tamaño; 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 con anterioridad.

Punto clave: Todas las URLs que se usen como parámetros para los métodos de la API de Protected Audience deben provenir de orígenes seguros: todos los recursos deben publicarse mediante 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

El resto de las propiedades son opcionales:

biddingLogicUrl^{1, 2}: Ejemplo: https://dsp.example/bid/custom-bikes/bid.js; Función: URL para las ofertas de JavaScript que se ejecuta en el worklet.
biddingWasmHelperUrl^{1, 2}: Ejemplo: https://dsp.example/bid/custom-bikes/bid.wasm; Función: URL para el código de WebAssembly controlado desde biddingLogicUrl.
updateUrl²: Ejemplo: https://dsp.example/bid/custom-bikes/update; Rol: Es la URL que muestra JSON para actualizar los atributos del grupo de interés. (Consulta Cómo actualizar los datos del público y los anuncios).
trustedBiddingSignalsUrl²: Ejemplo: https://dsp.example/trusted/bidding-signals; Rol: URL base para las solicitudes de pares 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 la licitación.
ads¹: Ejemplo: [bikeAd1, bikeAd2, bikeAd3]; Rol: Son los anuncios que se podrían renderizar para este grupo de interés.
adComponents: Ejemplo: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Rol: Componentes para anuncios compuestos por varias partes.

¹ Las propiedades biddingLogicUrl y ads son opcionales, pero se requieren 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 aún no se publica o para algún otro uso futuro, o es posible que se quedó temporalmente sin presupuesto publicitario.

² 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 la tienen.

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

Los objetos ads y adComponents incluyen una URL para una creatividad de anuncio y, de manera opcional, metadatos arbitrarios que se pueden usar durante la oferta.

Por ejemplo:

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

`leaveAdInterestGroup()`

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

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

Si un usuario regresa 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 de grupo para un solo usuario?

Chrome permite hasta 1,000 grupos de interés por propietario y hasta 1,000 propietarios de grupos de interés. Estos límites están diseñados como barandillas protectoras, por lo que no deben alcanzarse en el funcionamiento normal.

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

Como se indica en la explicación pública, debido a que un solo grupo de interés puede incluir varios anuncios posibles que podría mostrar, el grupo tendrá la oportunidad de volver a realizar la oferta en otro de sus anuncios para que actúe como un "anuncio de resguardo". siempre que su opción preferida esté por debajo del umbral. Esto significa que un anuncio pequeño y especializado que sigue por debajo del umbral de k-anonimato aún podría optar por participar en 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 empiece a publicarse, simplemente comienza a realizar ofertas con él en los casos en que desees que aparezca. No hay nada adicional que debas hacer.
Puedes tener un anuncio de resguardo que puedas 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 solo ofertar con el anuncio de resguardo en primer lugar. Quizás haga esto el 1% de las veces, por ejemplo, si ese es un buen nivel para asegurarse de que el resguardo permanezca por encima del umbral.

Recientemente, se discutieron otras formas en las que las cosas podrían funcionar. Por lo tanto, si tienes algún caso de uso para el cual este mecanismo plantearía un problema, continúa participando en la conversación pública sobre las formas en que la API podría mejorar.

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.