ID de reporting

Découvrez comment fonctionnent les ID de reporting dans une enchère Protected Audience

Présentation

Les ID de rapport sont des identifiants associés à une annonce qui peuvent être utilisés pour générer une enchère, la noter et créer des rapports. Les ID de reporting sont fournis par l'acheteur dans la configuration du groupe d'intérêt. Ils sont disponibles dans generateBid(), scoreAd(), reportResult() et reportWin() sous différentes conditions, qui sont abordées dans ce guide.

Les ID de reporting vous permettent de signaler un identifiant pour une annonce et d'activer des cas d'utilisation tels que les accords.

Il existe trois ID de rapport de deux types :

• ID de reporting non sélectionnables
  • buyerReportingId (chaîne)
  • buyerAndSellerReportingId (chaîne)
• ID de rapport sélectionnables
  • selectableBuyerAndSellerReportingIds (tableau de chaînes)

Les ID de rapport se comportent différemment selon que des ID de rapport sélectionnables sont utilisés ou non. Lorsque seuls des ID de reporting non sélectionnables sont utilisés, ils ne sont disponibles que dans les fonctions de reporting. Lorsque des ID de reporting sélectionnables sont utilisés, ainsi que des ID de reporting non sélectionnables si nécessaire, tous les ID définis deviennent également disponibles dans generateBid() et scoreAd().

ID de reporting non sélectionnables

buyerReportingId et buyerAndSellerReportingId sont des ID de rapport non sélectionnables définis dans la configuration du groupe d'intérêt. Ils sont disponibles dans les fonctions de reporting des acheteurs et des vendeurs. Les fonctions de reporting pour l'acheteur et le vendeur ne s'exécuteront que pour l'annonce gagnante, et elles recevront les ID de reporting définis pour cette annonce.

Lorsqu'elle est utilisée sans ID de rapport sélectionnables, la fonction de reporting de l'acheteur reçoit buyerReportingId ou buyerAndSellerReportingId selon le comportement d'écrasement, et la fonction de reporting du vendeur reçoit buyerAndSellerReportingId. Si ni buyerReportingId ni buyerAndSellerReportingId ne sont définis dans la configuration du groupe d'intérêt, la fonction reportWin() reçoit le nom du groupe d'intérêt (interestGroupName) de l'enchère gagnante.

Les ID non sélectionnables ne sont pas disponibles dans generateBid() et scoreAd() s'ils ne sont pas utilisés conjointement avec des ID de reporting sélectionnables.

ID de reporting dans les groupes d'intérêt

Les ID de reporting sont définis par l'acheteur pour chaque annonce d'un groupe de centres d'intérêt :

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

Rapports des vendeurs

Pendant la phase de création de rapports des vendeurs, la valeur buyerAndSellerReportingId devient disponible pour reportResult() :

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

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

Avant que l'ID ne soit disponible dans reportResult(), son k-anonymat est vérifié avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025). Si elle ne l'est pas, la fonction reportResult() s'exécutera quand même, mais la valeur de l'ID de reporting ne sera pas disponible dans la fonction.

Rapports sur les acheteurs

Lors de la phase de création de rapports des acheteurs de l'enchère, un ID de reporting devient disponible pour reportWin(). Si plusieurs ID de rapport sont définis dans le groupe d'intérêt, une règle de remplacement est appliquée, où buyerAndSellerReportingId remplace buyerReportingId :

• Si buyerAndSellerReportingId et buyerReportingId sont définis, buyerAndSellerReportingId remplacera buyerReportingId et sera disponible dans reportWin().buyerAndSellerReportingId
• Si seul buyerReportingId est défini, buyerReportingId sera disponible.
• Si ni buyerAndSellerReportingId ni buyerReportingId ne sont définis, interestGroupName sera disponible.

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

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

L'ID de rapport disponible dans reportWin() est vérifié pour le k-anonymat avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025). Si elle échoue au test d'anonymat k, reportWin() s'exécutera toujours, mais la valeur de l'ID de rapport ne sera pas disponible dans la fonction.

Seul buyerReportingId est défini

Si seul buyerReportingId est défini dans la configuration du groupe d'intérêt :

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

buyerReportingId est ensuite disponible dans reportWin() :

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

Avant d'être disponible pour reportWin(), le k-anonymat de buyerReportingId est vérifié avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025).

Seul buyerAndSellerReportingId est défini

Si seul buyerAndSellerReportingId est défini dans la configuration du groupe d'intérêt :

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

buyerAndSellerReportingId est ensuite disponible dans reportWin() :

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

Avant d'être disponible pour reportWin(), le k-anonymat de buyerAndSellerReportingId est vérifié avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025).

buyerAndSellerReportingId et buyerReportingId sont définis

Si buyerAndSellerReportingId et buyerReportingId sont définis dans la configuration du groupe d'intérêt :

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

Seul buyerAndSellerReportingId est alors disponible dans reportWin() en raison du comportement d'écrasement :

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

Avant d'être disponible pour reportWin(), le k-anonymat de buyerAndSellerReportingId est vérifié avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025).

buyerAndSellerReportingId et buyerReportingId ne sont pas définis

Si aucun ID de rapport n'est défini dans la configuration du groupe d'intérêt :

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

Le groupe d'intérêt name est alors disponible dans reportWin() :

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

Avant d'être disponible pour reportWin(), le nom du groupe d'intérêt (interestGroupName) est vérifié pour le k-anonymat avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025).

ID de reporting sélectionnables

Les ID de reporting sélectionnables permettent à un acheteur de sélectionner un ID lors de la génération d'enchères. Le navigateur met la valeur sélectionnée à la disposition de scoreAd() et des fonctions de reporting. La valeur selectableBuyerAndSellerReportingIds, qui est un tableau de chaînes, est fournie à generateBid(), et l'acheteur peut renvoyer un ID sélectionné sous la forme selectedBuyerAndSellerReportingId.

Les fonctions generateBid() et scoreAd() s'exécutent pour chaque annonce définie dans la configuration du groupe d'intérêt et reçoivent les ID de reporting pour chaque annonce. Les fonctions de reporting pour l'acheteur et le vendeur ne s'exécuteront que pour l'annonce gagnante, et elles recevront les ID de reporting définis pour cette annonce.

Lorsque des ID de rapport non sélectionnables sont utilisés conjointement avec des ID de rapport sélectionnables, leur comportement diffère de celui décrit dans la section précédente. Contrairement au comportement initial des ID de reporting non sélectionnables qui n'étaient disponibles que dans les fonctions de reporting, les ID de reporting sélectionnables permettent aux ID de reporting non sélectionnables d'être également disponibles dans generateBid() et scoreAd().

Groupe d'intérêt

Le champ "ID de reporting sélectionnables" selectableBuyerAndSellerReportingIds est un tableau de chaînes défini par l'acheteur dans le groupe d'intérêt pour une annonce. Vous pouvez également définir des ID de reporting non sélectionnables en plus des ID de reporting sélectionnables :

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

Génération d'enchères par les acheteurs

Si selectableBuyerAndSellerReportingIds a été défini dans la configuration du groupe d'intérêt, il devient disponible dans generateBid() avec les autres ID de reporting définis.

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
  };
}

L'acheteur peut choisir l'un des ID du tableau selectableBuyerAndSellerReportingIds dans generateBid() et renvoyer l'ID sélectionné sous la forme selectedBuyerAndSellerReportingId. L'enchère est refusée si la valeur sélectionnée ne figure pas dans le tableau selectableBuyerAndSellerReportingIds. Si selectableBuyerAndSellerReportingIds est défini dans la configuration du groupe d'intérêt et que l'acheteur ne renvoie pas selectedBuyerAndSellerReportingId à partir de generateBid(), les ID de reporting reviendront au comportement décrit pour les ID de reporting non sélectionnables.

Une enchère avec une valeur renvoyée pour selectedbuyerAndSellerReportingId ne peut remporter l'enchère que si la valeur de selectedbuyerAndSellerReportingId est k-anonyme conjointement avec buyerAndSellerReportingId (le cas échéant), buyerReportingId (le cas échéant), le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification jusqu'au premier trimestre 2025 au moins).

Évaluation des annonces de vendeurs

Pour le vendeur, le selectedBuyerAndSellerReportingId renvoyé par l'acheteur à partir de generateBid() devient disponible dans scoreAd(), ainsi que buyerAndSellerReportingId s'il a été défini dans la configuration du groupe d'intérêt.

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

  // ...
}

Rapports des vendeurs

Pour les rapports sur les vendeurs, le selectedBuyerAndSellerReportingId renvoyé par l'acheteur à partir de generateBid() devient disponible dans reportResult(), ainsi que buyerAndSellerReportingId, s'il a été défini dans le groupe d'intérêt.

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

Si selectableBuyerAndSellerReportingIds a été défini dans la configuration du groupe d'intérêt et que selectedBuyerAndSellerReportingId a été renvoyé par generateBid(), il ne peut pas remporter l'enchère, sauf si selectedBuyerAndSellerReportingId et buyerAndSellerReportingId (le cas échéant) sont k-anonymes avec le propriétaire du groupe d'intérêt, l'URL du script d'enchères, l'URL de rendu et la taille de l'annonce (la taille de l'annonce est exclue de cette vérification au moins jusqu'au premier trimestre 2025). Dans ce cas, reportResult() ne sera pas exécuté pour cette enchère. Par conséquent, si reportResult() est appelé avec une valeur pour selectedBuyerAndSellerReportingId, cela signifie que les ID de rapport ont passé le test de k-anonymat et que tous les ID de rapport définis seront disponibles dans reportResult().

Rapports sur les acheteurs

Si selectableBuyerAndSellerReportingIds a été défini dans la configuration du groupe d'intérêt et que selectedBuyerAndSellerReportingId a été renvoyé par generateBid(), tous les ID de reporting définis dans la configuration du groupe d'intérêt deviennent disponibles. Notez que, comme pour les rapports sur les vendeurs, si les ID de rapport ne sont pas k-anonymes, ils ne peuvent pas remporter l'enchère et reportWin() ne s'exécutera pas pour cette enchère.

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

  // ...
}

Remplacer les règles

Nous résumons ici les règles de remplacement pour les ID de rapports non sélectionnables et sélectionnables. Le navigateur détermine lequel des éléments selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId et du nom du groupe d'intérêt est transmis à reportWin(), selon la logique suivante :

• Si selectedBuyerAndSellerReportingId est renvoyé à partir d'une enchère, selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (si défini dans le groupe d'intérêt) et buyerReportingId (si défini dans le groupe d'intérêt) sont tous disponibles pour les rapports.
• Sinon, si buyerAndSellerReportingId est défini dans le groupe d'intérêt, seul buyerAndSellerReportingId est disponible pour les rapports.
• Sinon, si buyerReportingId est défini dans le groupe d'intérêt, seul buyerReportingId est disponible pour les rapports.
• Sinon, seul le groupe d'intérêt name est disponible pour le reporting.

Le tableau suivant décrit le comportement d'écrasement :

Interagir et envoyer des commentaires

• Pour en savoir plus sur les ID de reporting, consultez la section ID de reporting de la présentation de Protected Audience.
• GitHub : posez des questions et suivez les discussions dans les problèmes du dépôt de l'API.
• W3C : discutez des cas d'utilisation dans le secteur lors de l'appel WICG.
• Annonces : rejoignez ou consultez la liste de diffusion.
• Assistance pour les développeurs Privacy Sandbox : posez des questions et participez aux discussions sur le dépôt d'assistance pour les développeurs Privacy Sandbox.
• Chromium : signalez un bug Chromium pour poser des questions sur l'implémentation disponible pour les tests dans Chrome.