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

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

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

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

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

Protected Audience API की रिपोर्टिंग के बारे में खास जानकारी

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

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

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

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

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

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

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

सिग्नल

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

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

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

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

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 की नीलामी में, इवेंट-लेवल का डेटा रिपोर्ट करने के लिए 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 का इस्तेमाल किया जा सकता है.

फ़ेन्स्ड फ़्रेम और 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 का इस्तेमाल किया जा सकता है. इससे, Attribution Reporting की मदद से, इवेंट-लेवल और इकट्ठा की जा सकने वाली रिपोर्ट जनरेट की जा सकती है. ध्यान दें कि इन रिपोर्ट का इस्तेमाल कन्वर्ज़न को मेज़र करने के लिए किया जाता है. ये रिपोर्ट, इवेंट-लेवल और एग्रीगेट की जा सकने वाली उन रिपोर्ट से अलग होती हैं जो नीलामी और विज्ञापन फ़्रेम से जनरेट होती हैं. हम इस समस्या का ज़्यादा स्थायी समाधान उपलब्ध होने पर, इसके बारे में जानकारी देने वाला लेख पब्लिश करेंगे.

ट्रांज़िशन का तरीका

विज्ञापन बीकन रजिस्टर करते समय, 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 के बारे में जानकारी देने वाले दस्तावेज़ का Attribution Reporting सेक्शन देखें.

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

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

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

वर्कफ़्लो:

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

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

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

Protected Audience API से मिले डेटा को एग्रीगेट करना

Private Aggregation API का इस्तेमाल, Protected Audience के डेटा की रिपोर्टिंग के लिए किया जाता है. इससे खास जानकारी वाली रिपोर्ट जनरेट की जाती है. यह रिपोर्ट, बकेट में इकट्ठा किए गए डेटा की एग्रीगेट की गई रिपोर्ट होती है. बकेट को एग्रीगेशन की से दिखाया जाता है. साथ ही, कुछ जानकारी को की में कोड में बदला जा सकता है.

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

एपीआई के बारे में ज़्यादा जानने के लिए, Private Aggregation लेख पढ़ें.

नीलामी के सिग्नल एग्रीगेट करना

प्राइवेट एग्रीगेशन का इस्तेमाल करके, वर्कलेट में उपलब्ध सिग्नल को अपने सर्वर पर एग्रीगेट किया जा सकता है. सिग्नल एग्रीगेशन के लिए, 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
  });
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Shared Storage में नीलामी के सिग्नल सेव करना

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

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

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

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

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

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

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

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

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

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