IDs de informes

Obtén más información sobre cómo funcionan los IDs de informes en una subasta de Protected Audience

Descripción general

Los IDs de informes son identificadores asociados a un anuncio que están disponibles para generar una oferta, calificar una oferta y generar informes. El comprador proporciona los IDs de informes en la configuración del grupo de interés, y estos están disponibles en generateBid(), scoreAd(), reportResult() y reportWin() en diversas condiciones que se explican en esta guía.

Los IDs de informes te permiten informar un identificador para un anuncio y también habilitar casos de uso como los acuerdos.

Existen tres IDs de informes de dos tipos:

• IDs de informes no seleccionables
  • buyerReportingId (una cadena)
  • buyerAndSellerReportingId (una cadena)
• IDs de informes seleccionables
  • selectableBuyerAndSellerReportingIds (un array de cadenas)

Los IDs de informes se comportan de manera diferente según si se usan IDs de informes seleccionables. Cuando solo se usan IDs de informes no seleccionables, esos IDs solo están disponibles dentro de las funciones de informes. Cuando se usan IDs de informes seleccionables, junto con IDs de informes no seleccionables si es necesario, todos los IDs definidos también estarán disponibles dentro de generateBid() y scoreAd().

IDs de informes no seleccionables

buyerReportingId y buyerAndSellerReportingId son IDs de informes no seleccionables definidos en la configuración del grupo de interés que están disponibles en las funciones de informes del comprador y del vendedor. Las funciones de informes del comprador y del vendedor solo se ejecutarán para el anuncio ganador, y las funciones recibirán los IDs de informes definidos para ese anuncio ganador.

Cuando se usa sin IDs de informes seleccionables, la función de informes del comprador recibe buyerReportingId o buyerAndSellerReportingId según el comportamiento de anulación, y la función de informes del vendedor recibe buyerAndSellerReportingId. Si no se definen buyerReportingId ni buyerAndSellerReportingId en la configuración del grupo de interés, la función reportWin() recibe el nombre del grupo de interés (interestGroupName) de la oferta ganadora.

Los IDs no seleccionables no están disponibles dentro de generateBid() y scoreAd() si no se usan junto con IDs de informes seleccionables.

IDs de informes en grupos de interés

El comprador define los IDs de informes para cada anuncio de un grupo de interés:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Informes del vendedor

Durante la fase de informes del vendedor, el valor de buyerAndSellerReportingId estará disponible para reportResult():

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Antes de que el ID esté disponible dentro de reportResult(), se verifica su k-anonimato con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el primer trimestre de 2025). Si no es k-anónimo, la función reportResult() se ejecutará de todos modos, pero el valor del ID de informe no estará disponible dentro de la función.

Informes de compradores

Durante la fase de informes del comprador de la subasta, un ID de informe estará disponible para reportWin(). Si se define más de un ID de informe en el grupo de interés, se aplica una regla de anulación en la que buyerAndSellerReportingId anula buyerReportingId:

• Si se definen buyerAndSellerReportingId y buyerReportingId, buyerAndSellerReportingId anulará buyerReportingId y buyerAndSellerReportingId estará disponible dentro de reportWin().
• Si solo se define buyerReportingId, estará disponible buyerReportingId.
• Si no se definen buyerAndSellerReportingId ni buyerReportingId, estará disponible interestGroupName.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Se verifica el k-anonimato del ID de informe que está disponible en reportWin() con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el primer trimestre de 2025). Si no pasa la verificación de k-anonimato, reportWin() se seguirá ejecutando, pero el valor del ID de informe no estará disponible dentro de la función.

Solo se define buyerReportingId

Si solo se define buyerReportingId en la configuración del grupo de interés:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

Luego, buyerReportingId estará disponible dentro de reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

Antes de estar disponible para reportWin(), se verifica el k-anonimato de buyerReportingId con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el 1ᵉʳ trimestre de 2025).

Solo se define buyerAndSellerReportingId

Si solo se define buyerAndSellerReportingId en la configuración del grupo de interés:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Luego, buyerAndSellerReportingId estará disponible dentro de reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Antes de estar disponible para reportWin(), se verifica el k-anonimato de buyerAndSellerReportingId con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el 1ᵉʳ trimestre de 2025).

Se definen buyerAndSellerReportingId y buyerReportingId.

Si se definen buyerAndSellerReportingId y buyerReportingId en la configuración del grupo de interés, sucede lo siguiente:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Entonces, solo buyerAndSellerReportingId está disponible dentro de reportWin() debido al comportamiento de anulación:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Antes de estar disponible para reportWin(), se verifica el k-anonimato de buyerAndSellerReportingId con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el 1ᵉʳ trimestre de 2025).

No se definieron buyerAndSellerReportingId ni buyerReportingId.

Si no se define ningún ID de informes en la configuración del grupo de interés, sucederá lo siguiente:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

Luego, el grupo de interés name estará disponible dentro de reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

Antes de estar disponible para reportWin(), se verifica el k-anonimato del nombre del grupo de interés (interestGroupName) con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el primer trimestre de 2025).

IDs de informes seleccionables

Los IDs de informes seleccionables permiten que un comprador seleccione un ID durante la generación de la oferta, y el navegador pone el valor seleccionado a disposición de scoreAd() y las funciones de informes. El valor selectableBuyerAndSellerReportingIds, que es un array de cadenas, se proporciona a generateBid(), y el comprador puede devolver un ID seleccionado como selectedBuyerAndSellerReportingId.

Las funciones generateBid() y scoreAd() se ejecutarán para cada anuncio definido en la configuración del grupo de interés y recibirán los IDs de informes de cada anuncio. Las funciones de informes del comprador y del vendedor solo se ejecutarán para el anuncio ganador, y las funciones recibirán los IDs de informes definidos para ese anuncio ganador.

Cuando se usan IDs de informes no seleccionables junto con IDs de informes seleccionables, su comportamiento cambia con respecto al flujo de trabajo descrito en la sección anterior. A diferencia del comportamiento inicial de los IDs de informes no seleccionables que solo estaban disponibles dentro de las funciones de informes, los IDs de informes seleccionables permiten que los IDs de informes no seleccionables también estén disponibles dentro de generateBid() y scoreAd().

Grupo de interés

El campo de IDs de informes seleccionables (selectableBuyerAndSellerReportingIds) es un array de cadenas definido por el comprador en el grupo de interés de un anuncio. También se pueden definir IDs de informes no seleccionables junto con los IDs de informes seleccionables:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Generación de ofertas de compradores

Si se definió selectableBuyerAndSellerReportingIds en la configuración del grupo de interés, estará disponible dentro de generateBid() junto con otros IDs de informes que se hayan definido.

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

El comprador puede elegir uno de los IDs del array selectableBuyerAndSellerReportingIds en generateBid() y devolver el ID seleccionado como selectedBuyerAndSellerReportingId. La oferta se rechaza si el valor seleccionado no está en el array selectableBuyerAndSellerReportingIds. Si se define selectableBuyerAndSellerReportingIds en la configuración del grupo de interés y el comprador no devuelve selectedBuyerAndSellerReportingId desde generateBid(), los IDs de informes volverán al comportamiento descrito para los IDs de informes no seleccionables.

Una oferta con un valor devuelto para selectedbuyerAndSellerReportingId solo puede ganar la subasta si el valor de selectedbuyerAndSellerReportingId es k-anónimo de forma conjunta con buyerAndSellerReportingId (si está presente), buyerReportingId (si está presente), el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el 1ᵉʳ trimestre de 2025).

Puntuación de los anuncios de vendedor

Para el vendedor, el selectedBuyerAndSellerReportingId que devolvió el comprador desde generateBid() estará disponible en scoreAd(), junto con buyerAndSellerReportingId si se definió en la configuración del grupo de interés.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Informes del vendedor

Para los informes del vendedor, el selectedBuyerAndSellerReportingId que devolvió el comprador desde generateBid() está disponible en reportResult(), junto con buyerAndSellerReportingId, si se definió en el grupo de interés.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

Si se definió selectableBuyerAndSellerReportingIds en la configuración del grupo de interés y se devolvió selectedBuyerAndSellerReportingId desde generateBid(), no puede ganar la subasta, a menos que selectedBuyerAndSellerReportingId y buyerAndSellerReportingId (si está presente) sean k-anónimos con el propietario del grupo de interés, la URL de la secuencia de comandos de ofertas, la URL de renderización y el tamaño del anuncio (el tamaño del anuncio se excluye de esta verificación hasta, al menos, el primer trimestre de 2025), y no se ejecutará reportResult() para esa oferta. Por lo tanto, si se llama a reportResult() con un valor para selectedBuyerAndSellerReportingId, significa que los IDs de informes pasaron la verificación de k-anonimato y todos los IDs de informes definidos estarán disponibles dentro de reportResult().

Informes de compradores

Si se definió selectableBuyerAndSellerReportingIds en la configuración del grupo de interés y se devolvió selectedBuyerAndSellerReportingId desde generateBid(), estarán disponibles todos los IDs de informes que se definieron en la configuración del grupo de interés. Ten en cuenta que, de manera similar a los informes del vendedor, si los IDs de informes no son k-anónimos, no podrán ganar la subasta y reportWin() no se ejecutará para esa oferta.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Anular reglas

Aquí resumimos las reglas de anulación para los IDs de informes no seleccionables y los IDs de informes seleccionables. El navegador determina cuál de selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId y el nombre del grupo de interés se pasan a reportWin() con la siguiente lógica:

• Si se devuelve selectedBuyerAndSellerReportingId desde una oferta, selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (si se define en el grupo de interés) y buyerReportingId (si se define en el grupo de interés) estarán disponibles para la generación de informes.
• De lo contrario, si buyerAndSellerReportingId se define en el grupo de interés, solo buyerAndSellerReportingId estará disponible para los informes.
• De lo contrario, si buyerReportingId se define en el grupo de interés, solo buyerReportingId estará disponible para los informes.
• De lo contrario, solo el grupo de interés name estará disponible para la generación de informes.

En la siguiente tabla, se describe el comportamiento de la acción de sobrescribir:

Interactúa y comparte comentarios

• Para obtener más información sobre los IDs de informes, consulta la sección sobre el ID de informes de la explicación de Protected Audience.
• GitHub: Haz preguntas y sigue el debate en las entradas del repositorio de la API.
• W3C: Analiza los casos de uso del sector en la llamada de WICG.
• Anuncios: Únete a la lista de distribución o mírala.
• Asistencia para desarrolladores de Privacy Sandbox: Haz preguntas y únete a los debates en el repositorio de asistencia para desarrolladores de Privacy Sandbox.
• Chromium: Presenta un error de Chromium para hacer preguntas sobre la implementación disponible para probar en Chrome.