Protected Audience API की नीलामी की रिपोर्टिंग

Protected Audience API से जुड़ी नीलामी के डेटा और नतीजों को मेज़र करना

इस लेख में, अपने सर्वर पर Protected Audience API नीलामी के डेटा की रिपोर्ट करने के लिए उपलब्ध तरीकों के बारे में खास जानकारी दी गई है. साथ ही, माइग्रेशन के दौरान इस्तेमाल किए जा सकने वाले ट्रांज़िशन मैकेनिज़्म के बारे में जानकारी मिलेगी. यह जानकारी तब तक मिलेगी, जब तक कोई अन्य तरीका तैयार नहीं होता.

किसी विज्ञापन नीलामी से इकट्ठा की जाने वाली अहम मेट्रिक की रिपोर्ट बनाने के लिए, Protected Audience API इनके साथ काम करता है:

• प्राइवेट एग्रीगेशन, जो खास जानकारी वाली रिपोर्ट जनरेट करने के लिए, नीलामी के सिग्नल और नतीजों को इकट्ठा करता है.
• फ़ेंस किए गए फ़्रेम और iframe के लिए, Ads Reporting API. यह सुरक्षित ऑडियंस एपीआई वर्कलेट से संपर्क करने के लिए, फ़्रेम के अंदर एक चैनल है. एपीआई, इवेंट-लेवल के डेटा को नीलामी के सिग्नल के साथ जोड़ने की अनुमति देता है. Ads Reporting API की इवेंट-लेवल रिपोर्टिंग, ट्रांज़िशनल प्रोसेस है. ऐसा तब तक होता है, जब तक रिपोर्टिंग के लिए एक ज़्यादा निजी तरीका तैयार नहीं किया जाता.
• एट्रिब्यूशन रिपोर्टिंग की मदद से, कन्वर्ज़न डेटा को नीलामी के सिग्नल के साथ जोड़ा जा सकता है.
• शेयर किया गया स्टोरेज की मदद से, क्रॉस-ऑरिजिन स्टोरेज में नीलामी के सिग्नल लिखे जा सकते हैं. साथ ही, बाद में निजी एग्रीगेशन का इस्तेमाल करके, उस डेटा की रिपोर्ट की जा सकती है.

ध्यान दें: हमारा सुझाव है कि जारी रखने से पहले, आप प्राइवेट एग्रीगेशन, फ़ेंस किए गए फ़्रेम, शेयर किया गया स्टोरेज, और एट्रिब्यूशन रिपोर्टिंग से जुड़े दस्तावेज़ पढ़ें, क्योंकि इस दस्तावेज़ में मुख्य सिद्धांतों को भी आगे बढ़ाया गया है.

Protected Audience API की रिपोर्टिंग से जुड़ी खास जानकारी

Protected Audience का पूरा वर्कफ़्लो

Protected Audience API की नीलामी के फ़्लो का डेटा, मुख्य तौर पर तीन समयावधि में आपके सर्वर को रिपोर्ट किया जा सकता है: पब्लिशर की साइट से नीलामी के लिए नीलामी का समय, पब्लिशर की साइट पर विज्ञापन को रेंडर होने में लगने वाला समय, पब्लिशर की साइट पर रेंडर होने का समय, और उपयोगकर्ता के किसी दूसरी साइट पर कोई कार्रवाई करने का समय. कन्वर्ज़न का समय, नीलामी में इस्तेमाल हो सकने वाली किसी दूसरी साइट पर हो सकता है.

नीलामी के दौरान, रिपोर्टिंग वर्कलेट का इस्तेमाल करके नीलामी के डेटा की रिपोर्ट की जा सकती है. रेंडर होने के दौरान, iframe या फ़ेंस किए गए फ़्रेम से यूज़र ऐक्टिविटी के डेटा को रिपोर्ट किया जा सकता है. कन्वर्ज़न के दौरान, Attribution Reporting API का इस्तेमाल करके डेस्टिनेशन पेज से एट्रिब्यूशन डेटा की रिपोर्ट की जा सकती है.

रिपोर्टिंग की जगहें

नीलामी में खरीदार, generateBid() और reportWin() वर्कलेट में मौजूद सिग्नल को रिपोर्ट कर सकते हैं. वहीं, सेलर, scoreAd() और reportResult() में उपलब्ध सिग्नल को रिपोर्ट कर सकते हैं. नीलामी के बाहर, खरीदार और सेलर, विज्ञापन रेंडर करने वाले फ़्रेम से डेटा रिपोर्ट कर सकते हैं. साथ ही, वे उस साइट से भी डेटा रिपोर्ट कर सकते हैं जिससे कन्वर्ज़न हुआ था.

समयावधि	मंज़िल	जगह	डेटा उपलब्ध है	Reporting API उपलब्ध हैं
नीलामी	खरीदार	generateBid()	सिग्नल, नीलामी के नतीजे, और नीलामी की परफ़ॉर्मेंस	Private Aggregation API
		reportWin()		निजी एग्रीगेशन एपीआई Ads Reporting API
	विक्रेता	scoreAd()		Private Aggregation API
		reportResult()		निजी एग्रीगेशन एपीआई Ads Reporting API
प्रस्तुत करें	खरीदार / विक्रेता	पब्लिशर की साइट पर फ़्रेम	विज्ञापन फ़्रेम में इवेंट-लेवल का डेटा	निजी एग्रीगेशन एपीआई Ads Reporting API
कन्वर्ज़न	खरीदार / विक्रेता	कन्वर्ज़न साइट	कन्वर्ज़न साइट से मिला कन्वर्ज़न और इवेंट-लेवल का डेटा	Attribution Reporting API प्राइवेट एग्रीगेशन एपीआई Ads Reporting API

सूची में दी गई हर समयावधि के दौरान, खरीदारों और सेलर के पास अलग-अलग रिपोर्टिंग एपीआई का ऐक्सेस होगा, जो डेटा की रिपोर्ट करने के लिए उपलब्ध होते हैं. जैसे, नीलामी के सिग्नल, इवेंट-लेवल का डेटा, और कन्वर्ज़न डेटा.

Protected Audience API से जुड़ी नीलामी में उपलब्ध डेटा

नीलामी के दौरान Protected Audience API वर्कलेट से, रिपोर्ट किया जा सकता है.

सिग्नल

सिग्नल: यह नीलामी से जुड़ा डेटा, उपयोगकर्ता का डेटा, रीयल-टाइम डेटा, और ब्राउज़र डेटा होता है. यह डेटा, वर्कलेट में खरीदारों और विक्रेताओं को बिड जनरेट करने, विज्ञापन को स्कोर देने, और नीलामी के नतीजों की जानकारी देने के लिए उपलब्ध होता है.

सिग्नल	जानकारी	जगह की जानकारी सेट करें	उपयोगकर्ता	उपलब्धता
auctionSignals	नीलामी होने की जगह के हिसाब से उपलब्ध डेटा. इस डेटा में, पेज के कॉन्टेंट की जानकारी, पहले पक्ष के उपयोगकर्ता का डेटा वगैरह शामिल हो सकता है.	सेलर की ओर से नीलामी कॉन्फ़िगरेशन में, पब्लिशर साइट पर सेट किया गया.	खरीदार विक्रेता	बोली स्कोर विज्ञापन रिपोर्ट जनरेट करेंविज्ञापन रिपोर्ट नतीजे
directFromSellerSignals	auctionSignals, perBuyerSignals, sellerSignals के लिए वही डेटा है, लेकिन इस बात की गारंटी है कि सिग्नल बताए गए सेलर से ही मिलेगा.	विक्रेता के एचटीटीपी रिस्पॉन्स हेडर के ज़रिए सेट करें	खरीदार विक्रेता	बोली स्कोर विज्ञापन रिपोर्ट जनरेट करेंविज्ञापन रिपोर्ट नतीजे
browserSignals	ब्राउज़र से मिला कई डेटा (topWindowHostname, interestGroupOwner, renderUrl, adComponents, biddingDurationMsec, IGJoinCount, IGRecency, modelingSignals).	ब्राउज़र सेट करता है.	खरीदार विक्रेता	बोली स्कोर विज्ञापन रिपोर्ट जनरेट करेंविज्ञापन रिपोर्ट नतीजे
sellerSignals	विज्ञापन स्कोरिंग के लिए विक्रेता को दिए गए सिग्नल.	सेलर की ओर से नीलामी कॉन्फ़िगरेशन में, पब्लिशर साइट पर सेट किया गया.	विक्रेता	scoreAd reportWin reportResult
trustedScoringSignals	विज्ञापन स्कोरिंग के लिए सेलर को दिए गए रीयल-टाइम सिग्नल.	सेलर, पब्लिशर की साइट से नीलामी वाले कॉन्फ़िगरेशन में यूआरएल को सेट करता है.	विक्रेता	विज्ञापन के स्कोर की रिपोर्ट का नतीजा
perBuyerSignals	खास खरीदारों को दिया गया नीलामी से जुड़ा डेटा. विक्रेता नीलामी शुरू होने से पहले, खरीदारों के लिए कीमत की जानकारी हासिल कर सकता है. यह विज्ञापन अवसर के बारे में खरीदार की जानकारी है.	सेलर की ओर से नीलामी कॉन्फ़िगरेशन में, पब्लिशर साइट पर सेट किया गया.	खरीदार	बोली स्कोर विज्ञापन रिपोर्ट जनरेट करेंविज्ञापन रिपोर्ट नतीजे
trustedBiddingSignals	विज्ञापन के लिए बिडिंग के लिए, खरीदारों को दिए गए रीयल-टाइम सिग्नल.	खरीदार, विज्ञापन देने वाले की साइट पर मौजूद यूआरएल को तब सेट करता है, जब इंटरेस्ट ग्रुप सेट होता है.	खरीदार	generateBid
userBiddingSignals	खरीदार से मिला उपयोगकर्ता डेटा.	खरीदार की ओर से विज्ञापन देने वाले की साइट पर जाकर तब सेट किया जाता है, जब इंटरेस्ट ग्रुप सेट होता है .	खरीदार	generateBid

नीलामी कॉन्फ़िगरेशन ऑब्जेक्ट, वर्कलेट में सिग्नल के तौर पर उपलब्ध होने के लिए दिए गए डेटा का मुख्य सोर्स है. पब्लिशर और सेलर, नीलामी के कॉन्फ़िगरेशन में काम का और पहले पक्ष (ग्राहक) का डेटा दे सकते हैं. साथ ही, इन सिग्नल को दिलचस्पी के हिसाब से बनाए गए ग्रुप के डेटा की मदद से, विज्ञापन रेंडरिंग फ़्रेम से मिले इवेंट-लेवल के डेटा, और क्लिक मिलने वाले पेज से एट्रिब्यूशन डेटा की मदद से और बेहतर बनाया जा सकता है. रिपोर्ट किए गए डेटा का इस्तेमाल, खरीदार/सेलर की रिपोर्टिंग, बिलिंग, बजटिंग, मशीन लर्निंग मॉडल की ट्रेनिंग वगैरह के लिए किया जा सकता है.

अन्य उपलब्ध डेटा

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

Protected Audience API से जुड़ी नीलामी के बाहर, डेटा उपलब्ध होता है

Protected Audience API नीलामी के अलावा, दो ऐसी समयावधि होती हैं जिनमें डेटा, रिपोर्ट करने के लिए उपलब्ध होता है.

रेंडर होने के दौरान, जब पब्लिशर की साइट पर विज्ञापन रेंडर होता है, तो iframe या फ़ेंस किए गए फ़्रेम में मौजूद इवेंट-लेवल के डेटा को Protected Audience API नीलामी डेटा के साथ जोड़ा जा सकता है. साथ ही, आपके सर्वर को रिपोर्ट किया जा सकता है. इवेंट-लेवल के डेटा के उदाहरण में विज्ञापन इंप्रेशन, क्लिकथ्रू, होवर, और फ़्रेम के अंदर होने वाले अन्य सभी इवेंट शामिल होते हैं.

कन्वर्ज़न के दौरान, जब कोई उपयोगकर्ता ऐसे क्लिक मिलने की दर (सीटीआर) पर कोई कार्रवाई करता है जिसे नीलामी में वापस एट्रिब्यूट किया गया है, तो कन्वर्ज़न पेज के इवेंट-लेवल के डेटा को Protected Audience API नीलामी के डेटा से जोड़ा जा सकता है और आपके सर्वर को रिपोर्ट किया जा सकता है.

इवेंट-लेवल की रिपोर्टिंग

इवेंट-लेवल की रिपोर्ट में एक या उससे ज़्यादा इवेंट की ज़्यादा जानकारी होती है. इवेंट, नीलामी की जीत, विज्ञापन इंप्रेशन या कन्वर्ज़न हो सकता है. कम से कम साल 2026 तक, इवेंट-लेवल पर नीलामी के जीतने की रिपोर्ट पहले जैसी ही रहेगी. Protected Audience विज्ञापन को रेंडर करने के लिए, फ़ेंस किए गए फ़्रेम की ज़रूरत नहीं होगी. साथ ही, इवेंट-लेवल की रिपोर्टिंग के लिए, बिना पाबंदी वाले नेटवर्क के ऐक्सेस वाले iframe का इस्तेमाल किया जा सकता है. इसके अलावा, Ads Reporting API फ़ेन्स वाले फ़्रेम और iframe में उपलब्ध है. इससे नीलामी और कन्वर्ज़न डेटा को फ़्रेम के इवेंट-लेवल के डेटा से जोड़ा जा सकता है. इसे इस तरह से डिज़ाइन किया गया है कि नेटवर्क को माइग्रेट करने का तरीका आसान हो सके. ऐसा इसलिए, क्योंकि अपने सिस्टम को Protected Audience से माइग्रेट करने के दौरान, कम से कम 2026 तक मौजूदा रिपोर्टिंग इन्फ़्रास्ट्रक्चर का इस्तेमाल किया जा सकता है.

sendReportTo() के साथ इवेंट-लेवल पर नीलामी जीतने की रिपोर्ट

Protected Audience API से जुड़ी नीलामी में, इवेंट-लेवल के डेटा की रिपोर्ट करने का एक तरीका मौजूद है. यह तरीका, नीलामी में जीतने वाला sendReportTo() function है. यह फ़ंक्शन, खरीदार और सेलर रिपोर्टिंग वर्कलेट में उपलब्ध है. साथ ही, विज्ञापन रेंडरिंग शुरू होने पर ब्राउज़र, दिए गए यूआरएल स्ट्रिंग के लिए GET का अनुरोध करता है. अपने वर्कलेट में उपलब्ध किसी भी सिग्नल को, यूआरएल के क्वेरी पैरामीटर के तौर पर कोड में बदला जा सकता है.

उदाहरण के लिए, खरीदार reportWin() वर्कलेट में मौजूद बिडिंग की रकम को बिलिंग के मकसद से रिपोर्ट कर सकता है:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

sendReportTo() फ़ंक्शन का इस्तेमाल reportResult() से कॉल करने पर विक्रेता के लिए विन रिपोर्ट जनरेट करने के लिए और reportWin() से कॉल करने पर खरीदार के लिए विन रिपोर्ट जनरेट करने के लिए किया जा सकता है. sendReportTo() फ़ंक्शन, कम से कम 2026 तक उपलब्ध है,

जुड़ाव रिपोर्ट

जुड़ाव की रिपोर्ट में, विज्ञापन क्रिएटिव का इवेंट-लेवल का डेटा शामिल होता है. जैसे, इंप्रेशन या क्लिक का डेटा. यह डेटा, Protected Audience API नीलामी के सिग्नल से जुड़ा होता है, जिससे विज्ञापन रेंडर किया जाता है. विज्ञापन, नीलामी खत्म होने के बाद रेंडर होता है. इस वजह से, विज्ञापन को रेंडर करने वाले फ़्रेम के अंदर नीलामी सिग्नल उपलब्ध नहीं होते. अलग-अलग समयावधि के डेटा को जोड़ने के लिए, हम आपको दो ट्रांज़िशन प्रोसेस उपलब्ध कराते हैं, ताकि यूज़र ऐक्टिविटी की रिपोर्ट जनरेट की जा सकें.

ऊपर बताए गए sendReportTo() फ़ंक्शन का इस्तेमाल, नीलामी के डेटा को iframe के इवेंट-लेवल डेटा से जोड़ने के लिए किया जा सकता है. हालांकि, यह फ़ेंस किए गए फ़्रेम के लिए काम नहीं करता, क्योंकि एम्बेडर से कोई यूनीक आईडी नहीं भेजा जा सकता, क्योंकि एम्बेडर और फ़ेंस किए गए फ़्रेम के बीच बातचीत सीमित होती है. नीलामी के डेटा को, फ़ेंस किए गए फ़्रेम वाले विज्ञापन के इवेंट-लेवल के डेटा से जोड़ने के लिए, Ads Reporting API का इस्तेमाल किया जा सकता है.

अहम जानकारी: Protected Audience API में मौजूद इवेंट-लेवल की रिपोर्टिंग के मौजूदा तरीके, ट्रांज़िशन मैकेनिज़्म है. मौजूदा इस्तेमाल के उदाहरणों के साथ बेहतर तरीके से काम करने के लिए, इसका एक अन्य विकल्प भी डिज़ाइन किया जाएगा.

फ़ेंस किए गए फ़्रेम और iframe के लिए Ads Reporting API

फ़ेंस किए गए फ़्रेम और iframe के लिए, Ads Reporting API की मदद से, किसी विज्ञापन फ़्रेम के उपयोगकर्ता इवेंट-लेवल के डेटा को Protected Audience से जुड़ी नीलामी में सिग्नल के साथ जोड़ा जा सकता है.

Protected Audience API रिपोर्टिंग वर्कलेट में, registerAdBeacon() फ़ंक्शन की मदद से विज्ञापन बीकन रजिस्टर किया जा सकता है और क्वेरी पैरामीटर के तौर पर जोड़े गए सिग्नल का इस्तेमाल करके, रिपोर्टिंग यूआरएल में पास किया जा सकता है. उस कस्टम इवेंट के बारे में भी बताएं जिसे आपको रिपोर्टिंग यूआरएल के साथ असोसिएट करना है. इसके बाद, बाद में जब विज्ञापन को फ़ेंस किए गए फ़्रेम में रेंडर किया जाता है, तो window.fence.reportEvent() फ़ंक्शन को कॉल करके कस्टम इवेंट को ट्रिगर किया जा सकता है. फ़ेंस किए गए फ़्रेम के अंदर उपलब्ध डेटा को पेलोड के तौर पर जोड़ा जा सकता है.

registerAdBeacon() फ़ंक्शन सिर्फ़ रिपोर्टिंग फ़ंक्शन में उपलब्ध होता है. यह खरीदार के बिडिंग लॉजिक और सेलर के स्कोरिंग लॉजिक में उपलब्ध नहीं होता.

यहां दिए गए उदाहरण में, कैंपेन आईडी को इवेंट-लेवल के पेलोड के साथ क्लिक कोऑर्डिनेट के साथ जोड़ा गया है:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

इन वजहों से Fenced Frames Ads Reporting API, 2026 तक उपलब्ध रहेगा.

ज़्यादा जानकारी के लिए, जानकारी देने वाला सेक्शन देखें.

अबाधित नेटवर्क ऐक्सेस

फ़ेंस किए गए फ़्रेम, नेटवर्क रिसॉर्स को iframe की तरह ही लोड करने की अनुमति देंगे. साथ ही, आपके पास अपने सर्वर पर इवेंट-लेवल का डेटा, फ़ेंस किए गए फ़्रेम के अंदर भेजने की सुविधा होगी. फ़ेंस किए गए फ़्रेम से इवेंट-लेवल के डेटा को, sendReportTo() के साथ भेजे गए नीलामी डेटा से जोड़कर, बाद में सर्वर-साइड पर इवेंट-लेवल की रिपोर्ट जनरेट की जा सकती हैं. इस डेटा के बारे में, ऊपर नीलामी के इवेंट-लेवल की रिपोर्टिंग के तरीके वाले सेक्शन में चर्चा की गई थी.

आने वाले समय में नेटवर्क सीमित तौर पर दिखेगा.

अहम जानकारी: हमने अभी तक नेटवर्क के ऐक्सेस पर पाबंदी लगाने के लिए कोई ठोस समयसीमा तय नहीं की है. हालांकि, हम इन्हें कम करने पर काम कर रहे हैं, ताकि नेटवर्क को इन कमियों के हिसाब से ढलने के लिए काफ़ी समय मिल सके.

एट्रिब्यूशन रिपोर्ट

एट्रिब्यूशन रिपोर्ट की मदद से, किसी वेबसाइट पर होने वाले कन्वर्ज़न को, Protected Audience API नीलामी से चुने गए विज्ञापन से जोड़ा जा सकता है. उदाहरण के लिए, हो सकता है कि उपयोगकर्ता आपके प्रॉडक्ट के विज्ञापन पर क्लिक करे, उसने विज्ञापन देने वाले की साइट पर रीडायरेक्ट किया हो, वहां से खरीदारी की हो, और आपकी दिलचस्पी, दिखाए गए विज्ञापन को उसकी खरीदारी के लिए एट्रिब्यूट करना हो. Attribution Reporting API को Protected Audience API के साथ इंटिग्रेट किया जाएगा, ताकि पब्लिशर की साइट से नीलामी के डेटा और विज्ञापन देने वाली कंपनी की साइट के कन्वर्ज़न डेटा को आपस में जोड़ा जा सके.

हम एक ज़्यादा स्थायी समाधान तैयार करते हैं, लेकिन आप फ़ेंस किए गए फ़्रेम के लिए Ads Reporting API का इस्तेमाल एक ट्रांज़िशनल तरीके के तौर पर कर सकते हैं. इसकी मदद से, एट्रिब्यूशन रिपोर्टिंग की मदद से इवेंट-लेवल और एग्रीगेट की जा सकने वाली रिपोर्ट जनरेट की जा सकती हैं. ध्यान दें कि ये रिपोर्ट कन्वर्ज़न मेज़र करने के लिए होती हैं. साथ ही, ये नीलामी और विज्ञापन फ़्रेम से जनरेट होने वाली इवेंट-लेवल और एग्रीगेट की जा सकने वाली यूज़र ऐक्टिविटी की रिपोर्ट से अलग होती हैं. ज़्यादा स्थायी समाधान के लिए, हम तैयार होने पर जानकारी पब्लिश करेंगे.

ट्रांज़िशनल मैकेनिज़्म

विज्ञापन बीकन को रजिस्टर करते समय, आप reserved.top_navigation कीवर्ड का इस्तेमाल कर सकते हैं. यह कीवर्ड एट्रिब्यूशन स्रोत के तौर पर रजिस्टर होने की ज़रूरी शर्तें पूरी करने के लिए अपने आप बीकन का Attribution-Reporting-Eligible हेडर जोड़ देगा.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

रजिस्टर किए गए बीकन में इवेंट-लेवल का डेटा जोड़ने के लिए, आप इवेंट पेलोड के साथ फ़ेंस किए गए फ़्रेम से setReportEventDataForAutomaticBeacons() को कॉल कर सकते हैं.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

ज़्यादा जानने के लिए, Ads Reporting API की जानकारी देने वाला एट्रिब्यूशन रिपोर्टिंग सेक्शन देखें.

यूज़र ऐक्टिविटी और कन्वर्ज़न रिपोर्टिंग का उदाहरण

इस उदाहरण में, हम इसे खरीदार के नज़रिए से देखेंगे. इसकी दिलचस्पी नीलामी, विज्ञापन फ़्रेम, और कन्वर्ज़न साइट के डेटा को एक साथ जोड़ने में है.

इस वर्कफ़्लो में, खरीदार और सेलर के साथ मिलकर, नीलामी में एक यूनीक आईडी भेजता है. नीलामी के दौरान, खरीदार, नीलामी के डेटा के साथ यह यूनीक आईडी भेजता है. रेंडर और कन्वर्ज़न के समय, फ़ेंस किए गए फ़्रेम या iframe से डेटा को भी उसी यूनीक आईडी के साथ भेजा जाता है. बाद में, इन रिपोर्ट को एक साथ जोड़ने के लिए, यूनीक आईडी का इस्तेमाल किया जा सकता है.

वर्कफ़्लो:

1. नीलामी शुरू होने से पहले, खरीदार, अपनी प्रोग्रैम्ड तरीके से रीयल-टाइम बिडिंग ("RTB") बिड रिस्पॉन्स के हिस्से के तौर पर, सेलर को एक यूनीक आईडी भेजता है. आईडी को auctionId जैसे वैरिएबल के तौर पर सेट किया जा सकता है. आईडी को auctionConfig में perBuyerSignals के तौर पर पास किया जाता है और वह खरीदार के वर्कलेट में उपलब्ध हो जाता है.
2. नीलामी के दौरान, खरीदार विज्ञापन रेंडर होने के समय और कन्वर्ज़न के समय (registerAdBeacon()) के दौरान ट्रिगर होने वाले विज्ञापन बीकन को रजिस्टर कर सकता है.
   1. किसी विज्ञापन फ़्रेम इवेंट के लिए नीलामी के सिग्नल जोड़ने के लिए, auctionId को बीकन यूआरएल के क्वेरी पैरामीटर के तौर पर सेट करें.
   2. किसी कन्वर्ज़न इवेंट के लिए नीलामी के सिग्नल जोड़ने के लिए, बीकन यूआरएल में auctionId सेट करें.
3. विज्ञापन को रेंडर करते समय, नीलामी के दौरान रजिस्टर किए गए बीकन को इवेंट-लेवल के डेटा की मदद से ट्रिगर या बेहतर बनाया जा सकता है.
   1. फ़्रेम इवेंट को reportEvent() से ट्रिगर करें और इवेंट-लेवल का डेटा पास करें.
   2. setReportEventDataForAutomaticBeacons() के साथ एट्रिब्यूशन बीकन में इवेंट-लेवल पेलोड जोड़ें
   3. Attribution-Reporting-Register-Source हेडर वाले विज्ञापन बीकन के अनुरोधों का जवाब देकर, Attribution Reporting API के साथ विज्ञापन रजिस्टर करें.
4. कन्वर्ज़न के दौरान, नीलामी के दौरान रजिस्टर किए गए सोर्स को ट्रिगर किया जा सकता है.

ऊपर बताई गई प्रक्रिया के बाद, खरीदार के पास नीलामी रिपोर्ट, यूज़र ऐक्टिविटी रिपोर्ट, और कन्वर्ज़न रिपोर्ट होगी. इन सभी को एक खास कुंजी के ज़रिए एक साथ जोड़ा जाएगा. इस कुंजी का इस्तेमाल करके, एक-दूसरे को जोड़ा जा सकता है.

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

Protected Audience से जुड़ा डेटा इकट्ठा करना

Private एग्रीगेशन API वह तरीका है जिसका इस्तेमाल, सुरक्षित ऑडियंस के डेटा को रिपोर्ट करने के लिए किया जाता है. इससे, खास जानकारी वाली रिपोर्ट जनरेट होती है. इसमें, बकेट में इकट्ठा किए गए डेटा की ग़ैर-ज़रूरी और एग्रीगेट की गई रिपोर्ट होती हैं. बकेट को एग्रीगेशन की के ज़रिए दिखाया जाता है. कुछ जानकारी को कोड में बदला जा सकता है.

उदाहरण के लिए, किसी विज्ञापन इंप्रेशन इवेंट को अलग-अलग बकेट में गिना जा सकता है, जहां हर बकेट एक अलग विज्ञापन कैंपेन को दिखाती है. खास जानकारी वाली रिपोर्ट, इवेंट-लेवल की रिपोर्ट से इस तरह अलग होती है कि इसमें हर इवेंट के बारे में कोई जानकारी नहीं होती. इवेंट-लेवल की रिपोर्ट से यह पता लगाया जा सकता है कि उपयोगकर्ताओं A, B, और C ने कैंपेन 123 देखा है या नहीं. खास जानकारी वाली रिपोर्ट की मदद से, उन उपयोगकर्ताओं की संख्या मेज़र की जा सकती है जिन्होंने कैंपेन 123 देखा है. साथ ही, उपयोगकर्ता की निजता को सुरक्षित रखने के लिए, नॉइज़ जोड़ा गया है.

एपीआई के बारे में ज़्यादा जानकारी के लिए, प्राइवेट एग्रीगेशन लेख पढ़ें.

नीलामी सिग्नल इकट्ठा करना

प्राइवेट एग्रीगेशन का इस्तेमाल करके, वर्कलेट में मौजूद सिग्नल को अपने सर्वर पर एग्रीगेट किया जा सकता है. सिग्नल एग्रीगेशन के लिए, privateAggregation.contributeToHistogram() तरीके का इस्तेमाल किया जा सकता है. यह तरीका खरीदार बिडिंग वर्कलेट, सेलर के स्कोरिंग वर्कलेट , और खरीदार/सेलर रिपोर्टिंग वर्कलेट में उपलब्ध है.

इस उदाहरण में, जीतने वाली बिड को इंटरेस्ट ग्रुप के मालिक की बकेट में शामिल किया जाता है:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

यह एक सामान्य तरीका है. इसका इस्तेमाल तब किया जाता है, जब आपको जिन सिग्नल को इकट्ठा करना है वे इवेंट-लेवल के डेटा से न जुड़े हों और नीलामी के बाहर के किसी इवेंट से ट्रिगर न हों. नीलामी के सिग्नल को रिपोर्ट करने के बारे में ज़्यादा जानने के लिए, जानकारी देखें.

नीलामी के सिग्नल को इवेंट डेटा के साथ एग्रीगेट करना

विज्ञापन फ़्रेम में होने वाले इवेंट के बारे में सीमित जानकारी के साथ, नीलामी के सिग्नल इकट्ठा किए जा सकते हैं. उदाहरण के लिए, किसी कैंपेन और क्लिक इवेंट को दिखाने वाली बकेट बनाकर यह मेज़र किया जा सकता है कि किसी कैंपेन के विज्ञापन को कितने क्लिक मिले हैं. ध्यान दें कि विज्ञापन फ़्रेम से यह तय किया जा सकता है कि कौनसा इवेंट हुआ है. हालांकि, इवेंट-लेवल के पेलोड को अटैच नहीं किया जा सकता.

नीलामी के सिग्नल को इवेंट के हिसाब से इकट्ठा करने के लिए, privateAggregation.contributeToHistogramOnEvent(eventType, contribution) का इस्तेमाल किया जा सकता है. यह स्ट्रिंग, इवेंट टाइप और इवेंट के ट्रिगर होने पर रिपोर्ट किए जाने वाले योगदान की जानकारी देती है. आपके पास कस्टम इवेंट टाइप के हिसाब से तरीके को कॉल करने का विकल्प है. इसके बाद, विज्ञापन फ़्रेम से window.fence.reportEvent(eventType) पर कॉल करें और रिपोर्ट सबमिट करने के लिए ट्रिगर करें.

मान लें कि आपको यह मेज़र करना है कि किसी कैंपेन के विज्ञापन को कितने क्लिक मिले.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

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

// Ad frame
window.fence.reportEvent('click');

बाद में, विज्ञापन फ़्रेम से, reportEvent(eventType) को कॉल करके रिपोर्ट सबमिशन को ट्रिगर किया जा सकता है:

जानकारी देने वाले पैनल से, किसी फ़्रेम से निजी एग्रीगेशन योगदान को ट्रिगर करने के बारे में ज़्यादा जानें.

नीलामी के नतीजे और परफ़ॉर्मेंस की रिपोर्ट बनाना

रिज़र्व किए गए इवेंट टाइप वाले कीवर्ड (reserved.win, reserved.loss और reserved.always) पास करने पर, contributeToHistogramOnEvent(eventType, contribution) के साथ नीलामी में जीत या हार से ट्रिगर होने पर भी नीलामी के नतीजे इकट्ठा किए जा सकते हैं.

निजी एग्रीगेशन बेस वैल्यू की सूची देता है. इससे बकेट और वैल्यू को कैलकुलेट किया जा सकता है. नीलामी के नतीजों के लिए उपलब्ध बुनियादी वैल्यू में ये शामिल हैं: जीतने वाले विज्ञापन की बिड वैल्यू, बिड की वह वैल्यू जिसका दूसरा सबसे ज़्यादा स्कोर था, और बिड के अस्वीकार होने की वजह.

जब जीतने वाली बिड की रकम जैसी कुछ बेस वैल्यू दी जाती है, तो तय किया जा सकता है कि उस वैल्यू में से कितनी वैल्यू को जोड़ना या घटाना है. इसके बाद, फ़ाइनल वैल्यू को रिपोर्ट करें. उदाहरण के लिए, अगर 5 डॉलर की विजेता बिड को बेस वैल्यू के तौर पर दिया गया है, तो तीन डॉलर की असल वैल्यू का हिसाब लगाने के लिए, दो डॉलर की अपनी बिड को घटाया जा सकता है.

नीलामी के नतीजों की रिपोर्टिंग

आइए एक उदाहरण देखें, जिसमें आप नीलामी में हार गए और यह जानना चाहते हैं कि आपकी बोली, नीलामी में हिस्सा लेने वाली कीमत से कितनी दूर थी.

नीलामी में आपकी कितनी हार हुई, यह जानने के लिए, जीतने वाली बिड की कीमत से बिड की कीमत घटाई जा सकती है:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

रिपोर्ट सबमिट करने पर, रिपोर्ट की गई असल वैल्यू, स्केल की गई baseValue होगी. इसमें offset वैल्यू को शिफ़्ट किया जाएगा. ज़्यादा जानने के लिए, जानकारी देने वाला सेक्शन देखें.

परफ़ॉर्मेंस की रिपोर्टिंग

खरीदार और सेलर, यह रिपोर्ट कर सकते हैं कि स्क्रिप्ट को लागू होने में कितना समय लगा और भरोसेमंद सिग्नल को फ़ेच करने में कितना समय लगा. विक्रेता, अपनी अनुमति से हर खरीदार का बिड जनरेट होने का समय और भरोसेमंद बिडिंग सिग्नल समय इकट्ठा कर सकते हैं.

ज़्यादा जानने के लिए, जानकारी देने वाला देखें.

शेयर किए गए स्टोरेज में नीलामी के सिग्नल को स्टोर करना

शेयर किया गया स्टोरेज, अलग-अलग हिस्सों में बांटा गया और क्रॉस-ऑरिजिन स्टोरेज होता है. इसमें आसानी से डेटा लिखा जा सकता है. हालांकि, सेव की गई वैल्यू को पढ़ते और प्रोसेस करते समय, यह स्टोरेज अलग-अलग गेट से सुरक्षित होता है. Shared Storage API के लिए उपलब्ध विकल्पों में से एक प्राइवेट एग्रीगेशन है. शेयर किए गए स्टोरेज में मौजूद वैल्यू को सिर्फ़ वर्कलेट के अंदर पढ़ा जा सकता है. साथ ही, वर्कलेट से प्राइवेट एग्रीगेशन का इस्तेमाल करके उन वैल्यू की रिपोर्ट की जा सकती है.

Protected Audience API बिडिंग, स्कोरिंग, और रिपोर्टिंग वर्कलेट से, शेयर किए गए स्टोरेज को ऐक्सेस किया जा सकता है. बाद में किसी समय, शेयर किए गए स्टोरेज में मौजूद वैल्यू की रिपोर्ट, अपने सर्वर को निजी एग्रीगेशन का इस्तेमाल करके दी जा सकती है . यूआरएल चुनने की कार्रवाई के लिए, सेव की गई वैल्यू का भी इस्तेमाल किया जा सकता है.

Protected Audience API वर्कलेट से, शेयर किए गए स्टोरेज में कोई भी कुंजी और वैल्यू लिखी जा सकती है:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

बाद में, उस वैल्यू को निजी एग्रीगेशन से पढ़ने और भेजने के लिए, शेयर किए गए स्टोरेज के वर्कलेट को लोड किया जा सकता है:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

शेयर किए गए स्टोरेज के बारे में ज़्यादा जानने के लिए, Protected Audience API रिपोर्टिंग डेवलपर गाइड का 'शेयर किया गया स्टोरेज' सेक्शन, जानकारी, लाइव डेमो, और GitHub पर डेमो कोड देखें.

आगे क्या करना है?

हम आपके साथ मिलकर ऐसा एपीआई बनाना चाहते हैं जो सभी के काम आ सके.

एपीआई पर चर्चा करें

दूसरे प्राइवसी सैंडबॉक्स एपीआई की तरह, इस एपीआई को भी दस्तावेज़ के तौर पर दिखाया जाता है और सार्वजनिक तौर पर इस पर चर्चा की जाती है.

एपीआई के साथ प्रयोग करें

Protected Audience API के बारे में बातचीत में, एक्सपेरिमेंट किया जा सकता है और इसमें हिस्सा लिया जा सकता है.