खरीदार के तौर पर B&A के साथ इंटिग्रेट करना

बिडिंग और नीलामी (बीएंडए) सेवाएं, विज्ञापन खरीदारों और विज्ञापन देने वाले लोगों या कंपनियों के लिए सेवाओं का एक सेट है. यह सुरक्षित ऑडियंस (पीए) की नीलामी को आसान बनाने के लिए, ट्रस्टेड एक्ज़ीक्यूशन एनवायरमेंट (टीईई) में काम करता है. इस डेवलपर गाइड में बताया गया है कि खरीदार, Chrome के लिए B&A PA ऑक्शन के साथ कैसे इंटिग्रेट कर सकता है.

खास जानकारी

B&A Services के साथ Protected Audience नीलामी में हिस्सा लेने के लिए, खरीदार इंटरेस्ट ग्रुप (आईजी) को अपडेट करता है, ताकि नीलामी में देरी को कम करने के लिए पेलोड को ऑप्टिमाइज़ किया जा सके.

खरीदार को पेलोड ऑप्टिमाइज़ेशन से जुड़ी ये कार्रवाइयां करनी होंगी:

• joinAdInterestGroup() टास्क
  • सर्वर के अनुरोध के फ़्लैग सेट करना
  • विज्ञापन रेंडर करने वाले आईडी सेट करना
  • दिलचस्पी के हिसाब से बनाए गए ग्रुप की प्राथमिकताएं सेट करना
  • भरोसेमंद बिडिंग सिग्नल सेट अप करना
• generateBid() टास्क
  • ब्राउज़र सिग्नल पढ़ना
  • रेंडर यूआरएल वापस पाएं
  • रिटर्न रिपोर्टिंग आईडी

B&A के लिए एक जैसी दिलचस्पी वाला ग्रुप

यहां B&A PA ऑक्शन के लिए, दिलचस्पी के हिसाब से बनाए गए ग्रुप के कॉन्फ़िगरेशन का उदाहरण दिया गया है. इसमें पेलोड ऑप्टिमाइज़ेशन लागू किया गया है:

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

B&A और डिवाइस पर मौजूद दिलचस्पी वाले ग्रुप के कॉन्फ़िगरेशन में ये अंतर हैं:

• auctionServerRequestFlags फ़ील्ड की मदद से, ऐसे फ़्लैग सेट किए जा सकते हैं जो ब्राउज़र को B&A ऑक्शन पेलोड में कुछ डेटा शामिल न करने के लिए कहते हैं.
• userBiddingSignals वैल्यू को दिलचस्पी वाले ग्रुप में तय किया जा सकता है. हालांकि, हमारा सुझाव है कि omit-user-bidding-signals फ़्लैग का इस्तेमाल करके, उन्हें शामिल न करें. K/V सेवा का इस्तेमाल करके, हटाए गए सिग्नल दिए जा सकते हैं.
• adRenderId फ़ील्ड को उससे जुड़े renderURL के साथ सेट किया जाता है. हालांकि, सिर्फ़ adRenderId, B&A ऑक्शन पेलोड का हिस्सा बनेगा. नीलामी के दौरान generateBid() से मिला रेंडर यूआरएल, आईजी में तय किए गए रेंडर यूआरएल से मेल खाना चाहिए.
• रिपोर्टिंग आईडी, B&A IG में तय किए जाते हैं. हालांकि, इन्हें B&A ऑक्शन पेलोड में शामिल नहीं किया जाता. नीलामी के समय बाद में generateBid() से मिला रिपोर्टिंग आईडी, IG में तय किए गए रेंडर यूआरएल से मेल खाना चाहिए.
• ad.metadata और रिपोर्टिंग आईडी, B&A ऑक्शन पेलोड में शामिल नहीं होते हैं. इसके बजाय, यह डेटा Trusted Key/Value Service के इस्तेमाल से उपलब्ध होता है.

ध्यान दें कि ads में renderURL और रिपोर्टिंग आईडी अब भी दिलचस्पी वाले ग्रुप के कॉन्फ़िगरेशन में तय किए जाते हैं. हालांकि, ये नीलामी के अनुरोध के पेलोड में शामिल नहीं होते, क्योंकि ब्राउज़र यह जांच करता है कि बिडिंग सेवा के generateBid() फ़ंक्शन से मिले रेंडर यूआरएल और रिपोर्टिंग आईडी, दिलचस्पी वाले ग्रुप में तय की गई वैल्यू से मेल खाते हैं.

joinAdInterestGroup() टास्क

joinAdInterestGroup() कॉल के लिए, ये काम करने होंगे.

सर्वर के अनुरोध के फ़्लैग सेट करना

joinAdInterestGroup() कॉन्फ़िगरेशन के auctionServerRequestFlags फ़ील्ड में, ये फ़्लैग इस्तेमाल किए जा सकते हैं:

छोड़े गए डेटा को मैनेज करने के लिए, trustedBiddingSignals में ज़रूरी जानकारी उपलब्ध कराई जाती है. इन फ़्लैग का इस्तेमाल अलग-अलग किया जा सकता है. इनका एक साथ इस्तेमाल करना ज़रूरी नहीं है.

इस्तेमाल का उदाहरण:

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

विज्ञापन रेंडर आईडी सेट करना

B&A ऑक्शन पेलोड का साइज़ कम करने के लिए, दिलचस्पी वाले ग्रुप के ads और adComponents ऑब्जेक्ट हटा दिए जाते हैं. इस वजह से, ये ऑब्जेक्ट बिडिंग सेवा में चल रहे generateBid() फ़ंक्शन में उपलब्ध नहीं होते हैं.

विज्ञापन की जानकारी मौजूद न होने की समस्या को हल करने के लिए, खरीदार हर विज्ञापन से जुड़े एक आइडेंटिफ़ायर (adRenderId और adComponentRenderId) को इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में बनाए रखता है. पहचानकर्ता, 12 बाइट या इससे कम लंबाई वाला DOMString होना चाहिए. अगर आइडेंटिफ़ायर को Base64 की मदद से कोड में बदला गया है, तो इसकी लंबाई 12 बाइट या इससे कम होनी चाहिए.

विज्ञापन रेंडर करने वाले आईडी के साथ, दिलचस्पी वाले ग्रुप का उदाहरण:

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

विज्ञापनों से जुड़ा adRenderId, generateBid() में prevWins.browserSignals में उपलब्ध हो जाता है.

अनुरोध पेलोड में renderURL शामिल नहीं है. हालांकि, generateBid() से मिला रेंडर यूआरएल, दिलचस्पी वाले ग्रुप की कॉन्फ़िगरेशन में तय किए गए रेंडर यूआरएल से मेल खाना चाहिए. विज्ञापन टेक्नोलॉजी कंपनियां, trustedBiddingSignals में विज्ञापन का मेटाडेटा और अन्य जानकारी वापस भेज सकती हैं. इससे generateBid() के लागू होने के दौरान, बिड के लिए विज्ञापन रेंडर यूआरएल और विज्ञापन कॉम्पोनेंट रेंडर यूआरएल जनरेट किया जा सकता है.

दिलचस्पी वाले ग्रुप की प्राथमिकताएं सेट करना

Chrome, खरीदारों को दिलचस्पी वाले ग्रुप को प्राथमिकता देने की अनुमति देता है. अगर सेलर की ओर से सेट की गई, खरीदार के हिसाब से पेलोड के साइज़ की सीमा पूरी हो जाती है, तो दिलचस्पी के ग्रुप की प्राथमिकता की वैल्यू का इस्तेमाल किया जाता है. इससे, सेलर के लिए B&A ऑक्शन पेलोड जनरेट होने पर, किसी खरीदार के लिए कम प्राथमिकता वाले दिलचस्पी के ग्रुप हटा दिए जाते हैं. अलग-अलग खरीदारों के बीच दिलचस्पी वाले ग्रुप चुनने के लिए, ब्राउज़र, क्रम से लगाए गए पेलोड के साइज़ के आधार पर फ़ैसला लेता है. डिफ़ॉल्ट रूप से, हर खरीदार को बराबर साइज़ दिया जाता है. ध्यान दें कि प्राथमिकता तय करने की प्रोसेस, B&A सर्वर पर होती है. यह प्रोसेस, अनुरोध पेलोड जनरेट होने के दौरान नहीं होती.

नीलामी के समय प्राथमिकता का हिसाब लगाया जाता है. इसके लिए, खरीदार के प्राथमिकता वेक्टर (priorityVector) और सेलर के प्राथमिकता सिग्नल (prioritySignals) का इस्तेमाल किया जाता है. खरीदार के पास, सेलर के प्राथमिकता सिग्नल को बदलने का विकल्प होता है.

नीलामी के दौरान, ब्राउज़र प्राथमिकता के लिए priorityVector और prioritySignals में मौजूद मैचिंग कुंजियों के स्पार्स डॉट प्रॉडक्ट का हिसाब लगाता है. इस डायग्राम में, प्राथमिकता की गणना (4 * 2) + (3 * -1) से की जाती है, जिसे घटाकर 8 + -3 कर दिया जाता है. इसलिए, नीलामी के समय इस दिलचस्पी वाले ग्रुप की प्राथमिकता 5 होती है.

B&A में प्राथमिकता तय करने के लिए, अन्य सिग्नल भी इस्तेमाल किए जा सकते हैं:

ज़्यादा जानने के लिए, GitHub पर मौजूद जानकारी पढ़ें.

भरोसेमंद बिडिंग सिग्नल सेट अप करना

नीलामी के B&A पेलोड से कुछ डेटा हटा दिया जाएगा. इसलिए, generateBid() फ़ंक्शन को भरोसेमंद बिडिंग सिग्नल के तौर पर, हटाए गए डेटा को उपलब्ध कराने के लिए, कुंजी/वैल्यू सेवा का इस्तेमाल किया जा सकता है.

K/V सेवा, यह डेटा उपलब्ध करा सकती है:

• userBiddingSignals अगर खरीदार इसका इस्तेमाल करता है
• metadata हर विज्ञापन से जुड़ा होता है
• adRenderId हर विज्ञापन से जुड़ा होता है
• रिपोर्टिंग आईडी

इसके लिए, एक तरीका यह है कि भरोसेमंद बिडिंग सिग्नल की कुंजियों में एक यूनीक आइडेंटिफ़ायर शामिल किया जाए. इसके बाद, उससे जुड़ा डेटा अपने सर्वर को भेजा जाए, ताकि उसे कुंजी/वैल्यू सेवा में लोड किया जा सके. हालांकि, इसे लागू करने का तरीका विज्ञापन टेक्नोलॉजी और एपीआई पर निर्भर करता है.

यहां एक उदाहरण दिया गया है, जिसे लागू किया जा सकता है:

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

उदाहरण में, IG के लिए यूनीक आइडेंटिफ़ायर तय किया गया है. यह भरोसेमंद सिग्नल की कुंजी का हिस्सा बन जाता है. IG और उनसे जुड़ी वैल्यू की कुंजियां आपके सर्वर को भेजी जाती हैं, ताकि उन्हें Key/Value Service में लोड किया जा सके. नीलामी के दौरान बाद में, ब्राउज़र भरोसेमंद सिग्नल फ़ेच करता है और उन्हें खरीदार के generateBid() फ़ंक्शन में उपलब्ध कराता है.

ज़रूरत पड़ने पर, K/V से दिलचस्पी वाले ग्रुप के अपडेट सिग्नल को वापस पाएं

भरोसेमंद सिग्नल के लिए updateIfOlderThanMs कुंजी का इस्तेमाल, दिलचस्पी वाले ग्रुप को रोज़ाना के सामान्य अंतराल से पहले अपडेट करने के लिए किया जाता है. अगर updateIfOlderThanMs कुंजी के लिए मिलीसेकंड में दिखाई गई वैल्यू से ज़्यादा समय तक, इंटरेस्ट ग्रुप में शामिल नहीं हुआ जाता है या उसे अपडेट नहीं किया जाता है, तो इंटरेस्ट ग्रुप को updateURL मेकेनिज़्म के ज़रिए अपडेट किया जाएगा. ध्यान दें कि Chrome, दिलचस्पी वाले ग्रुप को हर 10 मिनट में एक बार से ज़्यादा अपडेट नहीं करेगा.

अगर B&A नीलामी में ऐसा विज्ञापन चुना जाता है जो ब्राउज़र में सेव किए गए इंटरेस्ट ग्रुप में शामिल किसी विज्ञापन से मैच नहीं करता है, तो ब्राउज़र नीलामी को पूरा नहीं कर पाएगा. updateIfOlderThanMs मेकेनिज़्म से यह पक्का करने में मदद मिल सकती है कि ब्राउज़र और B&A नीलामी, इंटरेस्ट ग्रुप में मौजूद विज्ञापनों के सेट से सहमत हों.

ज़्यादा जानने के लिए, एक्सप्लेनर पर जाएं.

generateBid() टास्क

generateBid() कॉल के लिए, ये काम करने होंगे.

ब्राउज़र के सिग्नल पढ़ने की अनुमति दें

B&A generateBid() कॉल में पास किया गया browserSignals ऑब्जेक्ट ऐसा दिखता है:

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

browserSignals में, बदली गई या नई प्रॉपर्टी उपलब्ध हैं:

generateBid() से रेंडर किया गया यूआरएल वापस पाएं

B&A ऑक्शन पेलोड में ads ऑब्जेक्ट शामिल नहीं किया गया है. इसलिए, generateBid() से मिले रेंडर यूआरएल को फिर से बनाना होगा. रेंडर यूआरएल को फिर से बनाने का तरीका, आपके लागू करने के तरीके पर निर्भर करता है. साथ ही, दिखाए गए यूआरएल को दिलचस्पी वाले ग्रुप में तय किए गए रेंडर यूआरएल से मैच करना चाहिए.

इसके लिए, एक तरीका यह है कि बेस यूआरएल को बनाए रखा जाए और टेंप्लेट में interestGroup और trustedBiddingSignals से मिली जानकारी भरी जाए.

इस उदाहरण में, रंग और प्रॉडक्ट के आधार पर चार विज्ञापन तय किए जा रहे हैं:

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

इसके बाद, हम उपयोगकर्ता के पसंदीदा रंग और प्रॉडक्ट की जानकारी को Key/Value Service में लोड करने के लिए भेजते हैं:

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

बाद में, जब नीलामी होती है, तब भरोसेमंद बिडिंग सिग्नल generateBid() में उपलब्ध हो जाते हैं. इस जानकारी का इस्तेमाल करके, यूआरएल को फिर से बनाया जा सकता है:

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

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

generateBid() से रिपोर्टिंग आईडी वापस पाएं

रिपोर्टिंग आईडी, B&A ऑक्शन पेलोड में शामिल नहीं होते हैं. इसलिए, आईडी generateBid() के लिए, भरोसेमंद बिडिंग सिग्नल के ज़रिए उपलब्ध हो जाता है. किस रिपोर्टिंग आईडी का इस्तेमाल करना है, यह तय हो जाने के बाद, चुने गए रिपोर्टिंग आईडी को generateBid() से वापस भेज दिया जाता है. दिए गए आईडी, दिलचस्पी के हिसाब से बनाए गए ग्रुप में तय किए गए आईडी से मेल खाने चाहिए.

इस उदाहरण में, विज्ञापन 1 को चुना गया है. साथ ही, इससे जुड़ा रेंडर आईडी, generateBid() से वापस मिल जाता है:

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

रिपोर्टिंग आईडी वापस मिलने के बाद, reportWin() से buyerReportingSignals तक उपलब्ध हो जाता है:

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

अगर generateBid() से buyerReportingId नहीं मिलता है, तो interestGroupName वैल्यू, buyerReportingId के बजाय buyerReportingSignals में उपलब्ध होती है.

ज़्यादा जानने के लिए, रिपोर्टिंग आईडी गाइड पर जाएं.

अगले चरण

आपके लिए ये संसाधन उपलब्ध हैं

ज़्यादा जानें

• Chrome में B&A नीलामी के कॉन्फ़िगरेशन के बारे में ज़्यादा जानें
• शुरू से आखिर तक लोकल टेस्टिंग कोडलैब को फ़ॉलो करके, B&A की मदद से Protected Audience को आज़माएं.

क्या आपका कोई सवाल है?

• अगर आपको बिडिंग और नीलामी सेवाओं के बारे में कोई सवाल पूछना है, तो बिडिंग और नीलामी सेवाओं की रिपॉज़िटरी में कोई समस्या सबमिट करें.