Intégrer B&A en tant qu'acheteur

Les services d'enchères et de mise aux enchères sont un ensemble de services destinés aux acheteurs et vendeurs d'annonces qui s'exécutent dans un environnement d'exécution sécurisé (TEE) pour faciliter les enchères Protected Audience (PA). Ce guide du développeur explique comment un acheteur peut intégrer une mise aux enchères par enchères publiques pour Chrome.

Présentation

Pour participer à une mise aux enchères Protected Audience avec les services de mise aux enchères et de mise aux enchères, l'acheteur met à jour le groupe d'intérêt (GI) afin d'optimiser la charge utile pour améliorer la latence des enchères.

Les tâches d'optimisation de la charge utile suivantes sont requises par l'acheteur:

Groupe d'intérêt pour les enchères et les mises aux enchères

Voici un exemple de configuration de groupe de centres d'intérêt pour une mise aux enchères d'enchères publiques de mise aux enchères avec optimisation de la charge utile:

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

Voici les différences entre les configurations d'enchères et de mise aux enchères et les configurations de groupes d'intérêts sur l'appareil:

Fields B&A IG IG sur l'appareil Inclus dans la charge utile d'enchères de mise aux enchères et d'enchères
auctionServerRequestFlags Occasion Non utilisée Non
userBiddingSignals Non recommandé Occasion Non, si l'indicateur omit-user-bidding-signals est défini
adRenderId dans ads et adComponents Occasion Non utilisée Si l'indicateur omit-ads est défini, adRenderId dans ads n'est disponible que dans browserSignals.prevWins de la charge utile. adRenderId défini dans adComponents n'est pas inclus dans la charge utile.

Si l'indicateur omit-ads n'est pas défini, disponible dans browserSignals.prevWins, interestGroup.adRenderIds et interestGroup.adComponentRenderIds.
renderURL dans ads et adComponents Occasion Occasion Non
metadata dans ads et adComponents Non utilisée Occasion Non
ID de création de rapports dans ads Occasion Occasion Non
  • Le champ auctionServerRequestFlags permet de définir des indicateurs qui indiquent au navigateur d'omettre certaines données dans la charge utile d'enchères d'enchères et de mise aux enchères.
  • La valeur userBiddingSignals peut être définie dans le groupe de centres d'intérêt, mais nous vous recommandons de l'omettre à l'aide de l'indicateur omit-user-bidding-signals. Les signaux omis peuvent être fournis à l'aide du service K/V.
  • Le champ adRenderId est défini avec le renderURL associé, mais seul le adRenderId fera partie de la charge utile de l'enchère d'enchères et de mise aux enchères. L'URL de rendu renvoyée par generateBid() plus tard pendant la mise aux enchères doit correspondre à l'URL de rendu définie dans l'IG.
  • Les ID de rapport sont définis dans l'IG d'enchères et mises aux enchères, mais ne sont pas inclus dans la charge utile d'enchères et mises aux enchères. L'ID de création de rapports renvoyé par generateBid() plus tard au moment des enchères doit correspondre à l'URL de rendu définie dans l'IG.
  • Les ID ad.metadata et de création de rapports ne sont pas inclus dans la charge utile des enchères d'enchères et d'enchères. Au lieu de cela, ces données sont disponibles via l'utilisation du service de clés/valeurs approuvé.

Notez que les renderURL et les ID de rapport dans ads sont toujours définis dans la configuration du groupe d'intérêt, mais qu'ils ne sont pas inclus dans la charge utile de la requête d'enchères, car le navigateur vérifie que l'URL de rendu et les ID de rapport renvoyés par la fonction generateBid() du service d'enchères correspondent aux valeurs définies dans le groupe d'intérêt.

joinAdInterestGroup() tâches

Les tâches suivantes doivent être effectuées pour l'appel joinAdInterestGroup().

Définir des indicateurs de requête de serveur

Le champ auctionServerRequestFlags de la configuration joinAdInterestGroup() accepte les options suivantes:

Option Description
omit-user-bidding-signals L'indicateur omit-user-bidding-signals omet l'objet userBiddingSignals dans la charge utile de l'enchère.

Si l'indicateur n'est pas défini, la valeur userBiddingSignals définie dans le groupe d'intérêts sera disponible dans generateBid() du service d'enchères.
omit-ads L'indicateur omit-ads indique au navigateur d'omettre les objets ads et adComponents dans la charge utile de l'enchère.

adRenderId sera disponible dans la propriété prevWins de browserSignals.

Si l'indicateur n'est pas défini, les champs adRenderIds et adComponentRenderIds de l'argument interestGroup de generateBid() contiennent les ID de rendu d'annonce correspondants.

Nous recommandons vivement aux acheteurs d'utiliser l'indicateur omit-ads. À l'avenir, le transfert d'ID de rendu et d'ID de rendu de composants d'annonces à partir du client pourrait être abandonné pour une meilleure optimisation de la charge utile.

Les données omises sont gérées en mettant à disposition des informations pertinentes dans trustedBiddingSignals. Les indicateurs peuvent être utilisés individuellement et ne doivent pas nécessairement être utilisés ensemble.

Exemple d'utilisation :

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

Définir des ID de rendu d'annonce

Pour réduire la taille de la charge utile d'enchères d'enchères et de mise aux enchères, les objets ads et adComponents du groupe d'intérêts sont omis. À leur tour, ces objets ne sont pas disponibles dans la fonction generateBid() exécutée dans le service d'enchères.

Pour gérer les informations d'annonce manquantes, l'acheteur gère un identifiant (adRenderId et adComponentRenderId) associé à chaque annonce dans la configuration du groupe d'intérêt. L'identifiant doit être une chaîne DOM de 12 octets maximum. Si l'identifiant est encodé en base64, sa longueur doit être inférieure ou égale à 12 octets.

Exemple de groupe de centres d'intérêt avec des ID de rendu d'annonce:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

Les adRenderId associés aux annonces seront disponibles dans prevWins.browserSignals en generateBid().

Bien que renderURL ne soit pas inclus dans la charge utile de la requête, l'URL de rendu renvoyée par generateBid() doit correspondre à l'URL de rendu définie dans la configuration du groupe de centres d'intérêt. Les technologies publicitaires peuvent renvoyer des métadonnées d'annonce et d'autres informations dans trustedBiddingSignals afin que l'URL d'affichage de l'annonce et l'URL d'affichage du composant de l'annonce puissent être générées pour l'enchère lors de l'exécution de generateBid().

Définir des priorités pour les groupes de centres d'intérêt

Chrome permet aux acheteurs de hiérarchiser les groupes de centres d'intérêt. Si la limite de taille de la charge utile par acheteur définie par le vendeur est atteinte, les valeurs de priorité des groupes d'intérêts sont utilisées pour supprimer les groupes d'intérêts de priorité inférieure pour un seul acheteur lorsque la charge utile d'enchères B&A est générée pour le vendeur. Pour sélectionner les groupes d'intérêts entre différents acheteurs, le navigateur prend sa décision en fonction de la taille de la charge utile sérialisée. Par défaut, chaque acheteur reçoit une taille égale. Notez que la hiérarchisation réelle se produit sur les serveurs d'enchères et de mise aux enchères, et non lors de la génération de la charge utile de la requête.

La priorité est calculée au moment des enchères à l'aide des vecteurs de priorité de l'acheteur (priorityVector) et des signaux de priorité du vendeur (prioritySignals). L'acheteur peut remplacer les signaux de priorité du vendeur.

Propriété Description
Vecteur de priorité L'acheteur fournit les vecteurs en tant que valeur de la clé priorityVector du service clés-valeurs.
Signaux prioritaires Le vendeur fournit les signaux en définissant priority_signals de la configuration des enchères.
Remplacements des signaux de priorité L'acheteur fournit le forçage dans le champ priority_signals_overrides de PerBuyerConfig dans la configuration des enchères.

Lors de l'enchère, le navigateur calcule le produit scalaire clairsemé des clés correspondantes dans priorityVector et prioritySignals pour la priorité. Dans le diagramme suivant, la priorité est calculée par (4 * 2) + (3 * -1), qui est réduite à 8 + -3. La priorité de ce groupe d'intérêts au moment des enchères est donc 5.

Chaque clé des objets de vecteur de priorité et de signaux de priorité est multipliée par les autres, puis les résultats sont additionnés pour calculer la priorité.
Figure 1: Calcul de la priorité à l'aide des vecteurs de l'acheteur et des signaux du vendeur

D'autres signaux peuvent également être utilisés pour établir des priorités dans les enchères et les mises aux enchères:

Signal Description
deviceSignals.one La valeur est toujours égale à 1. Elle permet d'ajouter une constante au produit scalaire.
deviceSignals.ageInMinutes Cette valeur décrit l'âge du groupe de centres d'intérêt (temps écoulé depuis l'adhésion la plus récente à un groupe de centres d'intérêt) en minutes,sous la forme d'un entier compris entre 0 et 43 200.
deviceSignals.ageInMinutesMax60 La valeur est la même que celle du signal ageInMinutes, mais elle est limitée à 60. Si le groupe date de plus d'une heure, la valeur renvoyée est 60.
deviceSignals.ageInHoursMax24 Cette valeur décrit l'âge du groupe de centres d'intérêt en heures, avec une limite de 24 heures. Si le groupe a plus d'un jour, la valeur 24 est renvoyée.
deviceSignals.ageInDaysMax30 Cette valeur décrit l'âge du groupe d'intérêts en jours, avec une limite de 30 jours. Si le groupe a plus de 30 jours, la valeur 30 est renvoyée.

Pour en savoir plus, consultez la présentation sur GitHub.

Configurer des signaux d'enchères de confiance

Étant donné que certaines données seront omises de la charge utile d'enchères d'enchères et de mise aux enchères, vous pouvez utiliser le service clés-valeurs pour fournir les données omises en tant que signaux d'enchères approuvés à la fonction generateBid().

Les données omises suivantes peuvent être fournies par le service K/V:

  • userBiddingSignals si utilisé par l'acheteur
  • metadata associé à chaque annonce
  • adRenderId associé à chaque annonce
  • ID de création de rapports
Les données omises du groupe de centres d'intérêt peuvent être envoyées au serveur de collecte de l'acheteur. Le serveur de collecte transfère les données au service clé-valeur, puis le navigateur les charge ultérieurement à partir de ce service.
Figure 2: Exemple de configuration de signaux approuvés

Vous pouvez par exemple inclure un identifiant unique dans les clés des signaux d'enchères de confiance, puis envoyer les données associées à votre serveur afin qu'elles puissent être chargées dans le service de clés-valeurs. Toutefois, l'implémentation concrète dépend de la technologie publicitaire, et l'API n'est pas prescriptive.

L'exemple suivant décrit une approche possible:

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

Dans cet exemple, un identifiant unique est défini pour un IG et fait partie de la clé des signaux approuvés. La clé de l'IG et les valeurs associées sont envoyées à votre serveur pour être chargées dans le service clé-valeur. Plus tard, pendant l'enchère, le navigateur récupère les signaux approuvés et les met à la disposition de la fonction generateBid() de l'acheteur.

Renvoyer le signal de mise à jour du groupe d'intérêts à partir de K/V si nécessaire

La clé updateIfOlderThanMs des signaux approuvés permet de mettre à jour le groupe d'intérêts plus tôt que l'intervalle quotidien habituel. Si le groupe de centres d'intérêt n'a pas été rejoint ni mis à jour pendant une durée supérieure à la valeur en millisecondes renvoyée pour la clé updateIfOlderThanMs, il sera mis à jour avec le mécanisme updateURL. Notez que Chrome ne met à jour les groupes de centres d'intérêt qu'une fois toutes les 10 minutes.

Si l'enchère d'enchères et de mise aux enchères renvoie une annonce gagnante qui ne correspond pas à l'une des annonces définies dans le groupe de centres d'intérêt stocké dans le navigateur, le navigateur échoue à l'enchère. Le mécanisme updateIfOlderThanMs peut être utile pour s'assurer que le navigateur et la mise aux enchères d'enchères et de mise aux enchères sont d'accord sur l'ensemble d'annonces du groupe d'intérêts.

Pour en savoir plus, consultez la vidéo explicative.

generateBid() tâches

Les tâches suivantes doivent être effectuées pour l'appel generateBid().

Lire les signaux du navigateur

L'objet browserSignals transmis à l'appel generateBid() de mise aux enchères et de mise aux enchères ressemble à ceci:

{
  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,
}

Les propriétés modifiées ou nouvelles suivantes sont disponibles dans browserSignals:

Propriété Description
prevWins prevWins est un tableau de tupels de temps et d'annonces. La durée représente le nombre de secondes écoulées depuis la dernière victoire de l'annonce associée au cours des 30 derniers jours.

Il a été modifié pour fournir adRenderId au lieu de l'objet ad.
wasmHelper Objet compilé du code fourni à partir de biddingWasmHelperURL.
dataVersion Un serveur approuvé peut éventuellement inclure un en-tête de réponse Data-Version numérique qui devient disponible dans generateBid().

Pour en savoir plus, consultez la présentation sur GitHub.

Renvoyer l'URL de rendu à partir de generateBid()

Étant donné que l'objet ads est omis dans la charge utile d'enchères de mise aux enchères et de mise aux enchères, l'URL de rendu renvoyée par generateBid() doit être recréée. La manière dont l'URL de rendu est recréée dépend de votre implémentation. L'URL renvoyée doit correspondre à l'URL de rendu définie dans le groupe de centres d'intérêt.

Une approche possible consiste à gérer une URL de base et à renseigner le modèle avec les informations de interestGroup et trustedBiddingSignals.

Dans cet exemple, nous définissons quatre annonces en fonction de la couleur et du produit:

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

Nous envoyons ensuite la couleur préférée de l'utilisateur et les informations sur le produit à charger dans le service clé-valeur:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

Plus tard, lorsque l'enchère est lancée, les signaux d'enchères fiables deviennent disponibles dans generateBid(). Ces informations peuvent être utilisées pour reconstruire l'URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

Renvoyer des ID de rapport à partir de generateBid()

Étant donné que les ID de création de rapports ne sont pas inclus dans la charge utile des enchères et mises aux enchères, l'ID devient disponible pour generateBid() via des signaux d'enchères de confiance. Une fois l'ID de reporting à utiliser déterminé, il est renvoyé par generateBid(). Les ID renvoyés doivent correspondre à ceux définis dans le groupe d'intérêts.

Dans cet exemple, l'annonce 1 est choisie, et son ID de rendu associé est renvoyé à partir de generateBid():

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

L'ID de rapport renvoyé devient disponible dans reportWin() via buyerReportingSignals:

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

Si buyerReportingId n'est pas renvoyé à partir de generateBid(), la valeur interestGroupName est disponible dans buyerReportingSignals au lieu de buyerReportingId.

Pour en savoir plus, consultez le guide sur les ID de rapport.

Étapes suivantes

Les ressources suivantes sont disponibles

En savoir plus

Vous avez des questions ?