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

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

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

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

Private एग्रीगेशन API क्या है

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

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

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

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

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

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

Private Aggregation API से जुड़े मुख्य कॉन्सेप्ट के बारे में ज़्यादा जानने के लिए, Private Aggregation API के बुनियादी सिद्धांत दस्तावेज़ देखें.

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

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

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

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

Private एग्रीगेशन एपीआई को स्थानीय तौर पर टेस्ट करने के लिए, chrome://settings/adPrivacy में मौजूद सभी Ad Privacy API को चालू करें.

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

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

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

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

उपयोग के उदाहरण

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

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

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

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

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

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

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

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

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

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

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

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

मल्टी-टच एट्रिब्यूशन

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

Protected Audience API की मदद से

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

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

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

शेयर किए गए स्टोरेज और 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 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

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

contributeToHistogramOnEvent()

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

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

यहां दिए गए उदाहरण में, नीलामी के जीतने वाले इवेंट के ट्रिगर होने पर, इंप्रेशन की रिपोर्ट भेजी जाती है. साथ ही, अगर विज्ञापन रेंडर करने वाले फ़ेंस किए गए फ़्रेम से 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() को कॉल करने से, डीबग मोड चालू हो जाता है. इस वजह से, एग्रीगेट की जा सकने वाली रिपोर्ट में, एन्क्रिप्ट (सुरक्षित) नहीं किए गए (क्लियरटेक्स्ट) पेलोड को शामिल किया जाता है. इसके बाद, इन पेलोड को एग्रीगेशन सेवा के लोकल टेस्टिंग टूल की मदद से प्रोसेस किया जा सकता है.

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

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

इन्हें हर संदर्भ में सिर्फ़ एक बार कॉल किया जा सकता है. बाद के किसी भी कॉल में अपवाद होगा.

// Enables debug mode
privateAggregation.enableDebugMode();

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

पुष्टि की रिपोर्ट करें

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

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

दिलचस्पी बढ़ाएं और सुझाव दें

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

• GitHub: एक्सप्लेनर पढ़ें, सवाल पूछें, और चर्चा में हिस्सा लें.
• डेवलपर सहायता: Privacy Sandbox के डेवलपर सहायता रेपो पर सवाल पूछें और चर्चाओं में शामिल हों.
• प्राइवेट एग्रीगेशन से जुड़ी नई सूचनाओं के लिए, Shared Storage API ग्रुप और Protected Audience API ग्रुप से जुड़ें.