रिपोर्टिंग आईडी

जानें कि Protected Audience API से जुड़ी नीलामी में, रिपोर्टिंग आईडी कैसे काम करते हैं

खास जानकारी

रिपोर्टिंग आईडी, विज्ञापन से जुड़े आइडेंटिफ़ायर होते हैं. इनका इस्तेमाल, बिड जनरेट करने, बिड को स्कोर करने, और रिपोर्टिंग के लिए किया जा सकता है. रिपोर्टिंग आईडी, खरीदार की ओर से इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में दिए जाते हैं. ये आईडी, generateBid(), scoreAd(), reportResult(), और reportWin() में अलग-अलग स्थितियों में उपलब्ध होते हैं. इन स्थितियों के बारे में इस गाइड में बताया गया है.

रिपोर्टिंग आईडी की मदद से, किसी विज्ञापन के लिए आइडेंटिफ़ायर की शिकायत की जा सकती है. साथ ही, ऑफ़र जैसे इस्तेमाल के उदाहरणों को भी चालू किया जा सकता है.

दो तरह के तीन रिपोर्टिंग आईडी होते हैं:

• ऐसे रिपोर्टिंग आईडी जिन्हें चुना नहीं जा सकता
  • buyerReportingId (एक स्ट्रिंग)
  • buyerAndSellerReportingId (एक स्ट्रिंग)
• चुने जा सकने वाले रिपोर्टिंग आईडी
  • selectableBuyerAndSellerReportingIds (स्ट्रिंग का कलेक्शन)

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

ऐसे रिपोर्टिंग आईडी जिन्हें चुना नहीं जा सकता

buyerReportingId और buyerAndSellerReportingId, ऐसे रिपोर्टिंग आईडी हैं जिन्हें चुना नहीं जा सकता. इन्हें एक जैसी पसंद के हिसाब से बनाए गए ग्रुप के कॉन्फ़िगरेशन में तय किया जाता है. ये आईडी, खरीदार और सेलर के रिपोर्टिंग फ़ंक्शन में उपलब्ध होते हैं. खरीदार और सेलर रिपोर्टिंग फ़ंक्शन, सिर्फ़ विज्ञापन जीतने वाले विज्ञापन के लिए चलेंगे. साथ ही, फ़ंक्शन को उस विज्ञापन के लिए तय किए गए रिपोर्टिंग आईडी मिलेंगे.

चुनने लायक रिपोर्टिंग आईडी के बिना इस्तेमाल करने पर, ओवरराइट करने के व्यवहार के आधार पर, खरीदार की रिपोर्टिंग फ़ंक्शन को buyerReportingId या buyerAndSellerReportingId मिलता है. साथ ही, सेलर की रिपोर्टिंग फ़ंक्शन को buyerAndSellerReportingId मिलता है. अगर इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में buyerReportingId और buyerAndSellerReportingId, दोनों में से कोई भी तय नहीं किया गया है, तो reportWin() फ़ंक्शन को जीतने वाली बिड का इंटरेस्ट ग्रुप का नाम (interestGroupName) मिलता है.

अगर चुने जा सकने वाले रिपोर्टिंग आईडी के साथ चुने जा सकने वाले आईडी का इस्तेमाल नहीं किया जाता है, तो generateBid() और scoreAd() में चुने जा सकने वाले आईडी उपलब्ध नहीं होते.

एक जैसी पसंद के हिसाब से बनाए गए ग्रुप में रिपोर्टिंग आईडी

रिपोर्टिंग आईडी, इंटरेस्ट ग्रुप में मौजूद हर विज्ञापन के लिए, खरीदार तय करता है:

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

सेलर रिपोर्टिंग

सेलर रिपोर्टिंग फ़ेज़ के दौरान, buyerAndSellerReportingId वैल्यू reportResult() के लिए उपलब्ध हो जाती है:

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

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

reportResult() में आईडी उपलब्ध होने से पहले, यह जांच की जाती है कि वह दिलचस्पी के ग्रुप के मालिक, बिडिंग स्क्रिप्ट के यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ k-anonymity के लिए सही है या नहीं. कम से कम 2025 की पहली तिमाही तक, विज्ञापन के साइज़ को इस जांच से बाहर रखा गया है. अगर यह k-anonymous नहीं है, तो भी reportResult() फ़ंक्शन चलेगा. हालांकि, फ़ंक्शन में रिपोर्टिंग आईडी की वैल्यू उपलब्ध नहीं होगी.

खरीदार की रिपोर्टिंग

नीलामी के दौरान, खरीदार की रिपोर्टिंग के चरण में reportWin() के लिए एक रिपोर्टिंग आईडी उपलब्ध हो जाता है. अगर इंटरेस्ट ग्रुप में एक से ज़्यादा रिपोर्टिंग आईडी तय किए गए हैं, तो ओवरराइट करने का नियम लागू होता है. इसमें buyerAndSellerReportingId, buyerReportingId को ओवरराइट करता है:

• अगर buyerAndSellerReportingId और buyerReportingId, दोनों की वैल्यू दी गई है, तो buyerAndSellerReportingId, buyerReportingId की वैल्यू को बदल देगा. साथ ही, buyerAndSellerReportingId की वैल्यू reportWin() में उपलब्ध होगी.
• अगर सिर्फ़ buyerReportingId तय किया गया है, तो buyerReportingId उपलब्ध होगा.
• अगर buyerAndSellerReportingId और buyerReportingId, दोनों की वैल्यू नहीं दी गई है, तो interestGroupName वैल्यू उपलब्ध होगी.

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

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

reportWin() में उपलब्ध रिपोर्टिंग आईडी की जांच, रुचि के ग्रुप के मालिक, बिडिंग स्क्रिप्ट यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ की जाती है. हालांकि, विज्ञापन के साइज़ की जांच, कम से कम 2025 की पहली तिमाही तक नहीं की जाएगी. अगर यह k-anonymity जांच में फ़ेल हो जाता है, तो reportWin() अब भी चलेगा, लेकिन फ़ंक्शन में रिपोर्टिंग आईडी की वैल्यू उपलब्ध नहीं होगी.

सिर्फ़ buyerReportingId के बारे में बताया गया है

अगर इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में सिर्फ़ buyerReportingId तय किया गया है, तो:

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

इसके बाद, buyerReportingId reportWin() में उपलब्ध होगा:

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

reportWin() के लिए उपलब्ध होने से पहले, buyerReportingId की जांच की जाती है कि वह K-anonymity की ज़रूरी शर्तें पूरी करता है या नहीं. यह जांच, इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट के यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ की जाती है. हालांकि, कम से कम 2025 की पहली तिमाही तक, विज्ञापन के साइज़ को इस जांच से बाहर रखा गया है.

सिर्फ़ buyerAndSellerReportingId तय किया गया है

अगर इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में सिर्फ़ buyerAndSellerReportingId तय किया गया है, तो:

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

इसके बाद, buyerAndSellerReportingId reportWin() में उपलब्ध होगा:

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

reportWin() के लिए उपलब्ध होने से पहले, buyerAndSellerReportingId की जांच की जाती है कि वह K-anonymity की ज़रूरी शर्तें पूरी करता है या नहीं. यह जांच, इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट के यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ की जाती है. हालांकि, कम से कम 2025 की पहली तिमाही तक, विज्ञापन के साइज़ को इस जांच से बाहर रखा गया है.

buyerAndSellerReportingId और buyerReportingId, दोनों एट्रिब्यूट की वैल्यू दी गई हो

अगर इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में buyerAndSellerReportingId और buyerReportingId, दोनों की वैल्यू दी गई है, तो:

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

इसके बाद, ओवरराइट करने की सुविधा की वजह से, reportWin() में सिर्फ़ buyerAndSellerReportingId उपलब्ध होगा:

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

reportWin() के लिए उपलब्ध होने से पहले, buyerAndSellerReportingId की जांच की जाती है कि वह K-anonymity की ज़रूरी शर्तें पूरी करता है या नहीं. यह जांच, इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट के यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ की जाती है. हालांकि, कम से कम 2025 की पहली तिमाही तक, विज्ञापन के साइज़ को इस जांच से बाहर रखा गया है.

buyerAndSellerReportingId और buyerReportingId, दोनों के बारे में नहीं बताया गया है

अगर एक जैसी पसंद के हिसाब से बनाए गए ग्रुप के कॉन्फ़िगरेशन में, दोनों रिपोर्टिंग आईडी तय नहीं किए गए हैं, तो:

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

इसके बाद, एक जैसी दिलचस्पी वाला ग्रुप name, reportWin() में उपलब्ध होगा:

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

reportWin() के लिए उपलब्ध होने से पहले, इंटरेस्ट ग्रुप के नाम (interestGroupName) की जांच की जाती है. यह जांच, इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट यूआरएल, रेंडर यूआरएल, और विज्ञापन के साइज़ के साथ की जाती है. हालांकि, विज्ञापन के साइज़ की जांच, साल 2025 की पहली तिमाही तक नहीं की जाएगी.

चुने जा सकने वाले रिपोर्टिंग आईडी

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

generateBid() और scoreAd() फ़ंक्शन, इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में तय किए गए हर विज्ञापन के लिए चलेंगे. साथ ही, उन्हें हर विज्ञापन के लिए रिपोर्टिंग आईडी मिलेंगे. खरीदार और सेलर रिपोर्टिंग फ़ंक्शन, सिर्फ़ विज्ञापन जीतने वाले विज्ञापन के लिए चलेंगे. साथ ही, फ़ंक्शन को उस विज्ञापन के लिए तय किए गए रिपोर्टिंग आईडी मिलेंगे.

जब चुने जा सकने वाले रिपोर्टिंग आईडी के साथ, चुने न जा सकने वाले रिपोर्टिंग आईडी का इस्तेमाल किया जाता है, तो उनका व्यवहार पिछले सेक्शन में बताए गए वर्कफ़्लो से बदल जाता है. चुने जा सकने वाले रिपोर्टिंग आईडी, चुने जा सकने वाले रिपोर्टिंग आईडी को generateBid() और scoreAd() में भी उपलब्ध कराते हैं. ऐसा, चुने जा सकने वाले रिपोर्टिंग आईडी के शुरुआती व्यवहार के उलट है, जो सिर्फ़ रिपोर्टिंग फ़ंक्शन में उपलब्ध होते हैं.

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

चुने जा सकने वाले रिपोर्टिंग आईडी फ़ील्ड - selectableBuyerAndSellerReportingIds - एक स्ट्रिंग कलेक्शन है. इसे, विज्ञापन के लिए खरीदार ने इंटरेस्ट ग्रुप में तय किया है. चुने जा सकने वाले रिपोर्टिंग आईडी के साथ-साथ, चुने नहीं जा सकने वाले रिपोर्टिंग आईडी भी तय किए जा सकते हैं:

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

खरीदार की बिड जनरेशन

अगर selectableBuyerAndSellerReportingIds को इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में तय किया गया था, तो यह generateBid() में उपलब्ध हो जाता है. साथ ही, इसमें तय किए गए अन्य रिपोर्टिंग आईडी भी उपलब्ध हो जाते हैं.

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

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

selectedbuyerAndSellerReportingId के लिए रिटर्न की गई वैल्यू वाली बिड सिर्फ़ तब नीलामी जीत सकती है, जब selectedbuyerAndSellerReportingId की वैल्यू, buyerAndSellerReportingId (अगर मौजूद है), buyerReportingId (अगर मौजूद है), इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट यूआरएल, रेंडर यूआरएल, और विज्ञापन साइज़ के साथ मिलकर, k-anonymous हो. कम से कम 2025 की पहली तिमाही तक, विज्ञापन साइज़ को इस जांच से बाहर रखा गया है.

सेलर के विज्ञापन को स्कोर करना

सेलर के लिए, generateBid() से खरीदार को लौटाए गए selectedBuyerAndSellerReportingId, scoreAd() में उपलब्ध हो जाते हैं. साथ ही, अगर दिलचस्पी के ग्रुप के कॉन्फ़िगरेशन में buyerAndSellerReportingId तय किया गया था, तो वह भी उपलब्ध हो जाता है.

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

  // ...
}

सेलर रिपोर्टिंग

सेलर रिपोर्टिंग के लिए, generateBid() से खरीदार को मिला selectedBuyerAndSellerReportingId, reportResult() में buyerAndSellerReportingId के साथ उपलब्ध हो जाता है. हालांकि, ऐसा तब ही होता है, जब selectedBuyerAndSellerReportingId को दिलचस्पी के ग्रुप में तय किया गया हो.

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

अगर selectableBuyerAndSellerReportingIds को इंटरेस्ट ग्रुप कॉन्फ़िगरेशन में तय किया गया था और selectedBuyerAndSellerReportingId को generateBid() से दिखाया गया था, तो यह नीलामी तब तक नहीं जीत सकती, जब तक कि selectedBuyerAndSellerReportingId और buyerAndSellerReportingId (अगर मौजूद है) इंटरेस्ट ग्रुप के मालिक, बिडिंग स्क्रिप्ट यूआरएल, रेंडर यूआरएल, और विज्ञापन साइज़ के साथ k-anonymous न हों. विज्ञापन साइज़ को कम से कम 2025 की पहली तिमाही तक इस जांच से बाहर रखा गया है. साथ ही, उस बिड के लिए reportResult() को लागू नहीं किया जाएगा. इसलिए, अगर reportResult() को selectedBuyerAndSellerReportingId की वैल्यू के साथ कॉल किया जाता है, तो इसका मतलब है कि रिपोर्टिंग आईडी, k-anonymity जांच में पास हो गए हैं. साथ ही, तय किए गए सभी रिपोर्टिंग आईडी, reportResult() में उपलब्ध होंगे.

खरीदार की रिपोर्टिंग

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

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

  // ...
}

नियमों को बदलना

यहां हम चुने जा सकने वाले और चुने न जा सकने वाले, दोनों रिपोर्टिंग आईडी के लिए, बदलाव करने के नियमों के बारे में खास जानकारी दे रहे हैं. selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId, और रुचि के ग्रुप के नाम में से किस जानकारी को reportWin() को भेजा जाए, यह ब्राउज़र तय करता है. इसके लिए, वह इस लॉजिक का इस्तेमाल करता है:

• अगर किसी बिड से selectedBuyerAndSellerReportingId दिखता है, तो रिपोर्टिंग के लिए selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (अगर दिलचस्पी के ग्रुप में तय किया गया है), और buyerReportingId (अगर दिलचस्पी के ग्रुप में तय किया गया है) सभी उपलब्ध होते हैं.
• अगर buyerAndSellerReportingId को एक जैसी पसंद के हिसाब से बनाए गए ग्रुप में तय किया गया है, तो रिपोर्टिंग के लिए सिर्फ़ buyerAndSellerReportingId उपलब्ध होगा.
• अगर buyerReportingId को एक जैसी पसंद के हिसाब से बनाए गए ग्रुप में तय किया गया है, तो रिपोर्टिंग के लिए सिर्फ़ buyerReportingId उपलब्ध होगा.
• ऐसा न करने पर, रिपोर्टिंग के लिए सिर्फ़ एक जैसी पसंद के हिसाब से बनाए गए ग्रुप name उपलब्ध होगा.

नीचे दी गई टेबल में, ओवरराइट करने के तरीके के बारे में बताया गया है:

दर्शकों से जुड़ना और सुझाव/राय देना या शिकायत करना

• रिपोर्टिंग आईडी के बारे में ज़्यादा जानने के लिए, सुरक्षित ऑडियंस के बारे में जानकारी देने वाले लेख का रिपोर्टिंग आईडी सेक्शन देखें.
• GitHub: एपीआई रिपॉज़िटरी पर, सवाल पूछें और समस्याओं के बारे में चर्चा करें.
• W3C: WICG कॉल में, इंडस्ट्री के इस्तेमाल के उदाहरणों के बारे में चर्चा करें.
• सूचनाएं: ईमेल पाने वाले लोगों की सूची में शामिल हों या उसे देखें.
• Privacy Sandbox के लिए डेवलपर सहायता: Privacy Sandbox के लिए डेवलपर सहायता रिपॉज़िटरी पर, सवाल पूछें और चर्चाओं में शामिल हों.
• Chromium: Chrome में टेस्ट करने के लिए उपलब्ध सुविधा को लागू करने के बारे में सवाल पूछने के लिए, Chromium बग फ़ाइल करें.