Private एग्रीगेशन एपीआई की खास जानकारी

शेयर किए गए स्टोरेज से, सुरक्षित ऑडियंस की सुविधा और क्रॉस-साइट डेटा का इस्तेमाल करके, एग्रीगेट डेटा की रिपोर्ट जनरेट करें.

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

लागू किए जाने की स्थिति

प्रस्ताव स्थिति
शेयर किए गए स्टोरेज की रिपोर्ट की पुष्टि करके, Private एग्रीगेशन एपीआई की अमान्य रिपोर्ट रोकें
एक्सप्लेनर		 Chrome में उपलब्ध
निजी एग्रीगेशन डीबग मोड की उपलब्धता, 3PC की ज़रूरी शर्तों पर निर्भर करती है
GitHub की समस्या		 Chrome M119 में उपलब्ध है
रिपोर्ट में देरी को कम करना
पूरी जानकारी		 Chrome M119 में उपलब्ध है
Google Cloud के लिए Private एग्रीगेशन एपीआई और एग्रीगेशन सर्विस के साथ काम करता है
Explainer		 Chrome M121 में उपलब्ध है
इकट्ठा की जा सकने वाली रिपोर्ट के पेलोड के लिए पैडिंग
पूरी जानकारी		 Chrome M119 में उपलब्ध है
नीलामी रिपोर्ट खरीदार की रिपोर्टिंग के लिए, निजी एग्रीगेशन डीबग मोड उपलब्ध है
एक्सप्लेनर		 Chrome M123 में ऐसा हो सकता है
फ़िल्टर करने के आईडी से जुड़ी सहायता
एक्सप्लेनर		 Chrome में, साल 2024 की दूसरी तिमाही में इसे लॉन्च किए जाने की उम्मीद है.

Private एग्रीगेशन एपीआई क्या है

Private एग्रीगेशन एपीआई की मदद से, डेवलपर Protected Audience API के डेटा और Shared Storage से मिले क्रॉस-साइट डेटा के साथ एग्रीगेट डेटा रिपोर्ट जनरेट कर सकते हैं.

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

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

मुख्य सिद्धांत

एग्रीगेशन कुंजी और एग्रीगेट की जा सकने वाली वैल्यू के साथ Private एग्रीगेशन एपीआई को कॉल करने पर, ब्राउज़र एग्रीगेट होने वाली रिपोर्ट जनरेट करता है.

इकट्ठा करने और बैच बनाने के लिए, एग्रीगेट की जा सकने वाली रिपोर्ट आपके सर्वर पर भेजी जाती हैं. बैच की गई रिपोर्ट, बाद में एग्रीगेशन सेवा से प्रोसेस की जाती हैं. इसके बाद, खास जानकारी वाली रिपोर्ट जनरेट की जाती है.

Private एग्रीगेशन एपीआई से जुड़े अहम सिद्धांतों के बारे में ज़्यादा जानने के लिए, प्राइवेट एग्रीगेशन एपीआई की बुनियादी बातें दस्तावेज़ देखें.

एट्रिब्यूशन रिपोर्टिंग से अंतर

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

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

इस एपीआई की जांच करें

Private एग्रीगेशन एपीआई को स्थानीय तौर पर टेस्ट किया जा सकता है. इसके लिए, chrome://flags/#privacy-sandbox-ads-apis पर Privacy Sandbox Ads API के एक्सपेरिमेंट फ़्लैग को चालू करें.

इन एपीआई का इस्तेमाल करने के लिए, Privacy Sandbox Ads API का एक्सपेरिमेंट 'चालू है' पर सेट करें
Privacy Sandbox Ads API के एक्सपेरिमेंट को 'चालू है' पर सेट करें, ताकि इन एपीआई का इस्तेमाल किया जा सके

एक्सपेरिमेंट और इसमें हिस्सा लेने में टेस्टिंग के बारे में ज़्यादा पढ़ें.

डेमो का इस्तेमाल करें

शेयर किए गए स्टोरेज के लिए Private एग्रीगेशन एपीआई का डेमो goo.gle/shared-storage-demo पर ऐक्सेस किया जा सकता है. यह कोड GitHub पर उपलब्ध है. डेमो, क्लाइंट-साइड की कार्रवाइयां लागू करता है और आपके सर्वर पर भेजी जाने वाली इकट्ठा की जा सकने वाली रिपोर्ट बनाता है.

आने वाले समय में, Protected Audience API के लिए, Private एग्रीगेशन एपीआई का डेमो पब्लिश किया जाएगा.

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

Private एग्रीगेशन, क्रॉस-साइट मेज़रमेंट के लिए एक सामान्य एपीआई है. इसका इस्तेमाल Shared Storage और Protected Audience API वर्कलेट में किया जा सकता है. सबसे पहले, यह तय करें कि आपको किस तरह की जानकारी इकट्ठा करनी है. ये डेटा पॉइंट, आपकी एग्रीगेशन कुंजियों के आधार होते हैं.

शेयर किए गए स्टोरेज के साथ

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

यूनीक रीच का मेज़रमेंट

ऐसे में, यह मेज़र किया जा सकता है कि कितने यूनीक उपयोगकर्ताओं ने उनका कॉन्टेंट देखा है. Private एग्रीगेशन एपीआई इस तरह का जवाब दे सकता है, जैसे कि "करीब 317 यूनीक उपयोगकर्ताओं ने Content ID 861 को देखा है."

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

डेमोग्राफ़िक्स मेज़रमेंट

हो सकता है कि आप उन उपयोगकर्ताओं की डेमोग्राफ़िक्स (उम्र, लिंग, आय, शिक्षा वगैरह) का आकलन करना चाहें जिन्होंने अलग-अलग साइटों पर आपका कॉन्टेंट देखा है.

निजी एग्रीगेशन से जवाब मिल सकता है, जैसे कि "करीब 317 यूनीक उपयोगकर्ता, 18 से 45 साल के उम्र के हैं और जर्मनी से हैं." किसी तीसरे पक्ष के डेमोग्राफ़िक्स डेटा को ऐक्सेस करने के लिए, शेयर किए गए स्टोरेज का इस्तेमाल करें. बाद में, एग्रीगेशन कुंजी में उम्र समूह और देश के डाइमेंशन को कोड में बदलकर, निजी एग्रीगेशन के साथ रिपोर्ट जनरेट की जा सकती है.

K+ फ़्रीक्वेंसी मेज़रमेंट

ऐसे उपयोगकर्ताओं की संख्या का पता लगाया जा सकता है जिन्होंने पहले से चुनी हुई K वैल्यू के लिए, किसी ब्राउज़र पर किसी कॉन्टेंट या विज्ञापन को कम से कम K बार देखा है.

निजी एग्रीगेशन से इस तरह का जवाब मिल सकता है, "करीब 89 उपयोगकर्ताओं ने Content ID को कम से कम तीन बार देखा है." काउंटर को अलग-अलग साइटों से, शेयर किए गए स्टोरेज में बढ़ाया जा सकता है और उसे वर्कलेट में पढ़ा जा सकता है. जब संख्या K तक पहुंच जाती है, तब प्राइवेट एग्रीगेशन के ज़रिए रिपोर्ट सबमिट की जा सकती है.

Protected Audience API की मदद से

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

Protected Audience API वर्कलेट से, सीधे sendHistogramReport() का इस्तेमाल करके डेटा को इकट्ठा किया जा सकता है. साथ ही, reportContributionForEvent() का इस्तेमाल करके, ट्रिगर के आधार पर डेटा की रिपोर्ट की जा सकती है. यह Protected Audience API का खास एक्सटेंशन है.

उपलब्ध फ़ंक्शन

ये फ़ंक्शन, Shared Storage और Protected Audience API वर्कलेट में उपलब्ध privateAggregation ऑब्जेक्ट में उपलब्ध हैं.

contributeToHistogram()

privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) को कॉल किया जा सकता है, जिसमें एग्रीगेशन कुंजी bucket और एग्रीगेट वैल्यू value के तौर पर होती है. bucket पैरामीटर के लिए, BigInt ज़रूरी है. value पैरामीटर के लिए, पूर्णांक नंबर डालना ज़रूरी है.

यहां दिए गए उदाहरण में बताया गया है कि रीच मेज़रमेंट के लिए, शेयर किए गए स्टोरेज में इसे कैसे कॉल किया जा सकता है:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

ऊपर दिए गए कोड के उदाहरण में, क्रॉस-साइट iframe कॉन्टेंट लोड होने पर निजी एग्रीगेशन को कॉल किया जाएगा. iframe कोड, वर्कलेट को लोड करता है. इसके बाद, वर्कलेट, Private एग्रीगेशन एपीआई को कॉल करता है. इसके लिए, Content ID को एग्रीगेशन कुंजी (बकेट) में बदला जाता है.

contributeToHistogramOnEvent()

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

privateAggregation.reportContributionForEvent(eventType, contribution) वाले तरीके में, ट्रिगर करने वाले इवेंट के बारे में बताने वाला eventType होता है. साथ ही, इवेंट के ट्रिगर होने पर contribution को सबमिट किया जाता है. नीलामी खत्म होने के बाद, ट्रिगर करने वाला इवेंट, नीलामी से ही मिल सकता है. जैसे, नीलामी में जीतने या हारने का इवेंट. इसके अलावा, यह विज्ञापन को रेंडर करने वाले फ़ेंस किए गए फ़्रेम से भी मिल सकता है. नीलामी वाले इवेंट की रिपोर्ट भेजने के लिए, रिज़र्व किए गए दो कीवर्ड reserved.win, reserved.loss, और reserved.always का इस्तेमाल करें. फ़ेंस किए गए फ़्रेम से किसी इवेंट से ट्रिगर हुई रिपोर्ट सबमिट करने के लिए, कस्टम इवेंट टाइप तय करें. फ़ेंस किए गए फ़्रेम से इवेंट ट्रिगर करने के लिए, फ़ेंस्ड फ़्रेम Ads Reporting API में मौजूद fence.reportEvent() तरीके का इस्तेमाल करें.

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

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

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

enableDebugMode()

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

वर्कलेट में privateAggregation.enableDebugMode() को कॉल करने से डीबग मोड चालू हो जाता है. इसकी वजह से, इकट्ठा की जा सकने वाली रिपोर्ट में एन्क्रिप्ट (सुरक्षित) नहीं किए गए पेलोड (cleartext) पेलोड शामिल होता है. इसके बाद, इन पेलोड को एग्रीगेशन सेवा के लोकल टेस्टिंग टूल की मदद से प्रोसेस किया जा सकता है.

डीबग मोड सिर्फ़ उन कॉलर के लिए उपलब्ध होता है जिनके पास तीसरे पक्ष की कुकी ऐक्सेस करने की अनुमति होती है. अगर कॉलर के पास तीसरे पक्ष की कुकी का ऐक्सेस नहीं है, तो enableDebugMode()` बिना किसी रुकावट के काम नहीं करेगा. इसका मतलब है कि तीसरे पक्ष की कुकी के बंद होने पर, डीबग मोड उपलब्ध नहीं होगा.

privateAggregation.enableDebugMode({ <debugKey: debugKey> }) को कॉल करके भी डीबग कुंजी सेट की जा सकती है. इसमें BigInt को डीबग कुंजी के तौर पर इस्तेमाल किया जा सकता है. डीबग कुंजी का इस्तेमाल, कुकी के आधार पर किए गए मेज़रमेंट से डेटा और निजी एग्रीगेशन मेज़रमेंट के डेटा को जोड़ने के लिए किया जा सकता है. इन्हें हर कॉन्टेक्स्ट के लिए सिर्फ़ एक बार कॉल किया जा सकता है. इसके बाद किए जाने वाले किसी भी कॉल को अनदेखा कर दिया जाएगा.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

शिकायत की पुष्टि की प्रक्रिया

शेयर किए गए स्टोरेज के लिए, आपको मिली इकट्ठा की गई रिपोर्ट सही हैं या नहीं, इसकी पुष्टि करने के लिए, शेयर किए गए स्टोरेज ऑपरेशन कॉल में एक संदर्भ आईडी जोड़ें. यह आईडी, भेजी गई रिपोर्ट में अटैच हो जाएगा. बाद में, उस आईडी का इस्तेमाल करके यह पुष्टि की जा सकती है कि रिपोर्ट, शेयर किए गए स्टोरेज की कार्रवाई से भेजी गई थी.

यह सुविधा Chrome M114+ में टेस्ट करने के लिए उपलब्ध है. Protected Audience API की रिपोर्ट की पुष्टि अभी टेस्ट के लिए उपलब्ध नहीं है.

ज़्यादा जानने के लिए, रिपोर्ट की पुष्टि से जुड़ी जानकारी देखें.

दिलचस्पी दिखाएं और सुझाव/राय दें या शिकायत करें

Private एग्रीगेशन एपीआई पर अभी चर्चा चल रही है. आने वाले समय में इसमें बदलाव हो सकता है. अगर आप इस एपीआई का इस्तेमाल करते हैं और आपको कोई सुझाव या राय देनी है या शिकायत करनी है, तो हमें ज़रूर बताएं.