Intégrer B&A en tant qu'acheteur

Les services d'enchères et de mise aux enchères (B&A) sont un ensemble de services destinés aux acheteurs et aux vendeurs d'annonces. Ils 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 s'intégrer à une enchère B&A PA pour Chrome.

Présentation

Pour participer à une enchère Protected Audience avec B&A Services, 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.

L'acheteur exige les tâches d'optimisation de la charge utile suivantes :

• joinAdInterestGroup() tâches
  • Définir les indicateurs de requête du serveur
  • Définir les ID de rendu des annonces
  • Définir les priorités des groupes d'intérêt
  • Configurer les signaux d'enchères de confiance
• generateBid() tâches
  • Lire les signaux du navigateur
  • URL de rendu du retour
  • ID de reporting des retours

Groupe d'intérêt pour la publicité et l'analyse

Voici un exemple de configuration de groupe d'intérêt pour une enchère B&A PA avec optimisation de la charge utile appliquée :

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 des groupes d'intérêt B&A et sur l'appareil :

• Le champ auctionServerRequestFlags permet de définir des indicateurs qui indiquent au navigateur d'omettre certaines données dans la charge utile des enchères B&A.
• La valeur userBiddingSignals peut être définie dans le groupe d'intérêt, mais il est recommandé de l'omettre en utilisant 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 B&A. L'URL de rendu renvoyée par generateBid() ultérieurement pendant la période d'enchères doit correspondre à l'URL de rendu définie dans le groupe d'insertion.
• Les ID de rapport sont définis dans le guide d'intégration des enchères et mises aux enchères, mais ne sont pas inclus dans la charge utile des enchères et mises aux enchères. L'ID de rapport renvoyé par generateBid() plus tard pendant l'enchère doit correspondre à l'URL de rendu définie dans le groupe d'intérêt.
• Les ID de ad.metadata et de rapports ne sont pas inclus dans la charge utile des enchères B&A. 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 demande 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 les indicateurs de requête de serveur

Le champ auctionServerRequestFlags de la configuration joinAdInterestGroup() accepte les indicateurs suivants :

Les données omises sont gérées en mettant à disposition les 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'annonces

Pour réduire la taille de la charge utile des enchères B&A, les objets ads et adComponents du groupe d'intérêt sont omis. Par conséquent, ces objets ne sont pas disponibles dans la fonction generateBid() exécutée dans le service d'enchères.

Pour gérer les informations manquantes sur les annonces, l'acheteur conserve un identifiant (adRenderId et adComponentRenderId) associé à chaque annonce dans la configuration du groupe d'intérêt. L'identifiant doit être une DOMString de 12 octets maximum. Si l'identifiant est encodé en Base64, sa longueur ne doit pas dépasser 12 octets.

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

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 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 de rendu de l'annonce et l'URL de rendu du composant d'annonce puissent être générées pour l'enchère lors de l'exécution de generateBid().

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

Chrome permet aux acheteurs de définir la priorité des groupes 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êt sont utilisées pour supprimer les groupes d'intérêt de priorité inférieure pour un seul acheteur lorsque la charge utile des enchères B&A est générée pour le vendeur. Pour sélectionner des groupes d'intérêt 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 a lieu sur les serveurs B&A, et non lorsque la charge utile de la requête est générée.

La priorité est calculée au moment de l'enchère à 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.

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

Des signaux supplémentaires peuvent également être utilisés pour établir des priorités dans B&A :

Pour en savoir plus, consultez l'explication sur GitHub.

Configurer des signaux d'enchères de confiance

Étant donné que certaines données seront omises du payload d'enchères B&A, vous pouvez utiliser le service de clés/valeurs pour fournir les données omises en tant que signaux d'enchères fiables à la fonction generateBid().

Le service K/V peut fournir les données omises suivantes :

• userBiddingSignals si utilisé par l'acheteur
• metadata associés à chaque annonce
• adRenderId associés à chaque annonce
• ID de création de rapports

Une approche possible consiste à 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é/valeur. Toutefois, l'implémentation réelle dépend de l'ad tech, et l'API n'est pas prescriptive.

L'exemple suivant décrit une approche qui peut être mise en œuvre :

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 l'exemple, un identifiant unique est défini pour un groupe d'intérêt et fait partie de la clé des signaux fiables. La clé de l'IG et ses valeurs associées sont envoyées à votre serveur pour être chargées dans le service de clé/valeur. Plus tard, pendant l'enchère, le navigateur récupère les signaux fiables et les met à disposition dans la fonction generateBid() de l'acheteur.

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

La clé updateIfOlderThanMs pour les signaux fiables est utilisée pour mettre à jour le groupe d'intérêt plus tôt que l'intervalle quotidien habituel. Si le groupe 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 pas à jour les groupes d'intérêt plus d'une fois toutes les 10 minutes.

Si l'enchère B&A renvoie une annonce gagnante qui ne correspond pas à l'une des annonces définies dans le groupe d'intérêt stocké dans le navigateur, l'enchère échouera. Le mécanisme updateIfOlderThanMs peut être utile pour s'assurer que le navigateur et l'enchère B&A s'accordent sur l'ensemble des annonces du groupe d'intérêt.

Pour en savoir plus, consultez l'explication.

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 B&A ressemble à ce qui suit :

{
  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 :

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

Étant donné que l'objet ads est omis dans la charge utile de l'enchère B&A, l'URL de rendu renvoyée par generateBid() doit être recréée. La façon 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 d'intérêt.

Une approche possible consiste à conserver une URL de base et à remplir 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 exécuté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 les ID de rapport à partir de generateBid()

Étant donné que les ID de rapport ne sont pas inclus dans la charge utile des enchères B&A, l'ID devient disponible pour generateBid() via des signaux d'enchères fiables. Une fois l'ID de reporting à utiliser déterminé, l'ID de reporting choisi est renvoyé à partir de generateBid(). Les ID renvoyés doivent correspondre à ceux définis dans le groupe d'intérêt.

Dans cet exemple, l'annonce 1 est sélectionnée 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é par 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 à votre disposition :

En savoir plus

• En savoir plus sur les configurations d'enchères B&A dans Chrome
• Testez Protected Audience avec B&A en suivant l'atelier de programmation sur les tests locaux de bout en bout.

Vous avez des questions ?

• Si vous avez une question sur les services d'enchères et de mise aux enchères, ouvrez un problème dans le dépôt des services B&A.