Private एग्रीगेशन API से जुड़ी बुनियादी बातें

Private Aggregation API के मुख्य कॉन्सेप्ट

यह दस्तावेज़ किसके लिए है?

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

  • अगर आप क्रॉस-साइट मेज़रमेंट के लिए रिपोर्टिंग सिस्टम बनाने वाले डेवलपर हैं.
  • अगर आप मार्केटर, डेटा साइंटिस्ट या खास जानकारी वाली रिपोर्ट का इस्तेमाल करने वाला कोई अन्य व्यक्ति हैं, तो इन तरीकों को समझने से आपको ऑप्टिमाइज़ की गई खास जानकारी वाली रिपोर्ट पाने के लिए, डिज़ाइन से जुड़े फ़ैसले लेने में मदद मिलेगी.

मुख्य शब्द

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

  • एग्रीगेशन बटन (जिसे बकेट भी कहा जाता है), डेटा पॉइंट का पहले से तय किया गया कलेक्शन होता है. उदाहरण के लिए, हो सकता है कि आपको जगह की जानकारी के उस डेटा की बकेट इकट्ठा करनी हो जहां ब्राउज़र, देश के नाम की जानकारी देता है. एग्रीगेशन कुंजी में एक से ज़्यादा डाइमेंशन हो सकते हैं. उदाहरण के लिए, आपके कॉन्टेंट विजेट का देश और आईडी.
  • एग्रीगेट की जा सकने वाली वैल्यू, एग्रीगेशन की कुंजी में इकट्ठा किया गया एक अलग डेटा पॉइंट होता है. अगर आपको यह मेज़र करना है कि फ़्रांस के कितने उपयोगकर्ताओं ने आपका कॉन्टेंट देखा है, तो France एग्रीगेशन बटन में डाइमेंशन है और 1 की viewCount एग्रीगेट की जा सकने वाली वैल्यू है.
  • एग्रीगेट की जा सकने वाली रिपोर्ट, ब्राउज़र में जनरेट और एन्क्रिप्ट (सुरक्षित) की जाती हैं. Private Aggregation API के लिए, इसमें किसी एक इवेंट का डेटा होता है.
  • एग्रीगेशन सेवा, खास जानकारी वाली रिपोर्ट बनाने के लिए, एग्रीगेट की जा सकने वाली रिपोर्ट का डेटा प्रोसेस करती है.
  • खास जानकारी वाली रिपोर्ट, एग्रीगेशन सेवा का आखिरी आउटपुट है. इसमें, उपयोगकर्ता का एग्रीगेट किया गया ग़ैर-ज़रूरी डेटा और कन्वर्ज़न का पूरा डेटा शामिल होता है.
  • वर्कलेट, इंफ़्रास्ट्रक्चर का एक हिस्सा है. इसकी मदद से, JavaScript के खास फ़ंक्शन चलाए जा सकते हैं और अनुरोध करने वाले को जानकारी वापस दी जा सकती है. वर्कलेट में, JavaScript को चलाया जा सकता है. हालांकि, बाहरी पेज के साथ इंटरैक्ट या उससे संपर्क नहीं किया जा सकता.

निजी एग्रीगेशन वर्कफ़्लो

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

डेटा, क्लाइंट से कलेक्टर पर जाता है. इसके बाद, समरी रिपोर्ट जनरेट करने के लिए, एग्रीगेशन सेवा पर जाता है.
  1. Private Aggregation API को कॉल करने पर, क्लाइंट (ब्राउज़र) एग्रीगेट की जा सकने वाली रिपोर्ट जनरेट करता है और उसे इकट्ठा करने के लिए आपके सर्वर पर भेजता है.
  2. आपका सर्वर, क्लाइंट से रिपोर्ट इकट्ठा करता है और उन्हें एग्रीगेशन सेवा को भेजने के लिए एक साथ भेजता है.
  3. ज़रूरत के मुताबिक रिपोर्ट इकट्ठा करने के बाद, आपको उन्हें एक साथ भेजना होगा. साथ ही, उन्हें एग्रीगेशन सेवा को भेजना होगा. यह सेवा, भरोसेमंद एक्सीक्यूशन एनवायरमेंट में चलती है. इससे आपको खास जानकारी वाली रिपोर्ट जनरेट करने में मदद मिलेगी.

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

एग्रीगेशन की कुंजी

एग्रीगेशन बटन ("बटन" के लिए छोटा) उस बकेट को दिखाता है जहां एग्रीगेट की जा सकने वाली वैल्यू इकट्ठा की जाएंगी. एक या उससे ज़्यादा डाइमेंशन को पासकोड में एन्कोड किया जा सकता है. डाइमेंशन, किसी ऐसे पहलू के बारे में जानकारी देता है जिसके बारे में आपको ज़्यादा जानकारी चाहिए. जैसे, उपयोगकर्ताओं की उम्र समूह या किसी विज्ञापन कैंपेन के इंप्रेशन की संख्या.

उदाहरण के लिए, आपके पास ऐसा विजेट हो सकता है जिसे कई साइटों पर एम्बेड किया गया हो. साथ ही, आपको उन उपयोगकर्ताओं के देश का विश्लेषण करना हो जिन्होंने आपका विजेट देखा है. आपको "मेरे विजेट को देखने वाले कितने उपयोगकर्ता, देश X से हैं?" जैसे सवालों के जवाब चाहिए. इस सवाल की रिपोर्ट करने के लिए, एक एग्रीगेशन पासकोड सेट अप किया जा सकता है, जो दो डाइमेंशन को कोड में बदलता है: विजेट आईडी और देश आईडी.

निजी एग्रीगेशन एपीआई को दी गई कुंजी एक BigInt है, जिसमें कई डाइमेंशन होते हैं. इस उदाहरण में, डाइमेंशन के तौर पर विजेट आईडी और देश का आईडी इस्तेमाल किया गया है. मान लें कि विजेट आईडी में ज़्यादा से ज़्यादा चार अंक हो सकते हैं, जैसे कि 1234. साथ ही, हर देश को वर्णमाला के क्रम में किसी नंबर से मैप किया गया है. जैसे, अफ़ग़ानिस्तान को 1, फ़्रांस को 61, और जिम्बाब्वे को 195. इसलिए, एग्रीगेट की जा सकने वाली कुंजी सात अंकों की होगी. इसमें पहले चार वर्ण WidgetID के लिए और आखिरी तीन वर्ण CountryID के लिए रिज़र्व होंगे.

मान लें कि पासकोड से, फ़्रांस (देश का आईडी 061) के उन उपयोगकर्ताओं की संख्या का पता चलता है जिन्होंने विजेट आईडी 3276 देखा है. एग्रीगेशन पासकोड 3276061 है.

एग्रीगेशन की कुंजी
विजेट आईडी देश का आईडी
3276 061

एग्रीगेशन पासकोड को हैशिंग की सुविधा की मदद से भी जनरेट किया जा सकता है. जैसे, SHA-256. उदाहरण के लिए, स्ट्रिंग {"WidgetId":3276,"CountryID":67} को हैश किया जा सकता है और फिर 42943797454801331377966796057547478208888578253058197330928948081739249096287n की BigInt वैल्यू में बदला जा सकता है. अगर हैश वैल्यू में 128 बिट से ज़्यादा हैं, तो इसे छोटा किया जा सकता है, ताकि यह 2^128−1 की तय सीमा से ज़्यादा न हो.

शेयर किए गए स्टोरेज के वर्कलेट में, crypto और TextEncoder मॉड्यूल को ऐक्सेस किया जा सकता है. इनकी मदद से, हैश जनरेट किया जा सकता है. हैश जनरेट करने के बारे में ज़्यादा जानने के लिए, MDN पर SubtleCrypto.digest() देखें.

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

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

एग्रीगेट की जा सकने वाली वैल्यू

एग्रीगेट की जा सकने वाली वैल्यू को कई उपयोगकर्ताओं के लिए हर कुंजी के हिसाब से जोड़ा जाता है, ताकि खास जानकारी वाली रिपोर्ट में खास जानकारी वाली वैल्यू के तौर पर एग्रीगेट की गई अहम जानकारी जनरेट की जा सके.

अब, पहले पूछे गए उदाहरण वाले सवाल पर वापस जाएं: "मेरे विजेट को देखने वाले उपयोगकर्ताओं में से कितने फ़्रांस से हैं?" इस सवाल का जवाब कुछ ऐसा दिखेगा: "मेरे विजेट आईडी 3276 को देखने वाले करीब 4,881 उपयोगकर्ता, फ़्रांस से हैं." हर उपयोगकर्ता के लिए, एग्रीगेट की जा सकने वाली वैल्यू 1 होती है. साथ ही, "4881 उपयोगकर्ता" एग्रीगेट की गई वैल्यू होती है. यह उस एग्रीगेशन की सभी एग्रीगेट की जा सकने वाली वैल्यू का योग होती है.

एग्रीगेशन की कुंजी एग्रीगेट की जा सकने वाली वैल्यू
विजेट आईडी देश का आईडी देखे जाने की संख्या
3276 061 1

इस उदाहरण के लिए, हम विजेट देखने वाले हर उपयोगकर्ता के लिए वैल्यू को 1 से बढ़ाते हैं. सिग्नल-टू-नॉइज़ रेशियो को बेहतर बनाने के लिए, इकट्ठा की जा सकने वाली वैल्यू को स्केल किया जा सकता है.

योगदान का बजट

निजी एग्रीगेशन एपीआई को किए गए हर कॉल को योगदान कहा जाता है. उपयोगकर्ता की निजता को सुरक्षित रखने के लिए, किसी व्यक्ति से ज़्यादा योगदान नहीं लिए जा सकते.

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

योगदान का बजट, पैरामीटर L1 से दिखाया जाता है. इसे हर दिन 10 मिनट के लिए 216 (65,536) पर सेट किया गया है. साथ ही, इसमें 220 (1,048,576) का बैकस्टॉप भी है. इन पैरामीटर के बारे में ज़्यादा जानने के लिए, एक्सप्लेनर देखें.

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

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

हर रिपोर्ट के लिए योगदान की सीमा

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

शेयर किए गए स्टोरेज के लिए, एक ही run() या selectURL() ऑपरेशन में किए गए योगदान को एक रिपोर्ट में रखा जाता है. Protected Audience के लिए, किसी नीलामी में एक ही ऑरिजिन से किए गए योगदान को एक साथ रखा जाता है.

पैडिंग के साथ योगदान

पैडिंग की सुविधा की मदद से, योगदानों में और बदलाव किए जाते हैं. पेलोड में पैडिंग करने से, एग्रीगेट की जा सकने वाली रिपोर्ट में एम्बेड किए गए योगदान की सही संख्या की जानकारी सुरक्षित रहती है. पैडिंग, तय लंबाई तक पहुंचने के लिए, null योगदान (यानी वैल्यू 0) के साथ पेलोड को बढ़ाती है.

एग्रीगेट की जा सकने वाली रिपोर्ट

जब उपयोगकर्ता Private Aggregation API को कॉल करता है, तो ब्राउज़र एग्रीगेट की जा सकने वाली रिपोर्ट जनरेट करता है. इन रिपोर्ट को बाद में एग्रीगेशन सेवा प्रोसेस करती है, ताकि खास जानकारी वाली रिपोर्ट जनरेट की जा सकें. एग्रीगेट की जा सकने वाली रिपोर्ट, JSON फ़ॉर्मैट में होती है. इसमें योगदान की एन्क्रिप्ट की गई सूची होती है. हर सूची में एक {aggregation key, aggregatable value} जोड़ा होता है. अलग-अलग डेटा को मिलाकर तैयार की गई रिपोर्ट, एक घंटे तक की देरी के साथ भेजी जाती हैं.

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

डीबग मोड चालू होने पर, एग्रीगेट की जा सकने वाली रिपोर्ट का उदाहरण:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

एग्रीगेट की जा सकने वाली रिपोर्ट की समीक्षा करने के लिए, chrome://private-aggregation-internals पेज पर जाएं:

Private Aggregation API के इंटरनल पेज का स्क्रीनशॉट

जांच के मकसद से, "चुनी गई रिपोर्ट भेजें" बटन का इस्तेमाल करके, रिपोर्ट को तुरंत सर्वर पर भेजा जा सकता है.

एग्रीगेट की जा सकने वाली रिपोर्ट इकट्ठा करना और उन्हें एक साथ भेजना

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

  • शेयर किए गए स्टोरेज के लिए: /.well-known/private-aggregation/report-shared-storage
  • Protected Audience के लिए: /.well-known/private-aggregation/report-protected-audience

इन एंडपॉइंट पर, आपको एक सर्वर चलाना होगा. यह सर्वर, क्लाइंट से भेजी गई ऐसी रिपोर्ट इकट्ठा करता है जिन्हें एग्रीगेट किया जा सकता है.

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

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

आईडी फ़िल्टर करना

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

PAA SS डायग्राम

इस सुविधा का इस्तेमाल आज ही शुरू करने के लिए, यहां कुछ तरीके दिए गए हैं. इनका इस्तेमाल करके, इस सुविधा को अपने मौजूदा वर्शन में लागू किया जा सकता है.

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

अगर आपने अपने फ़्लो में Shared Storage API का इस्तेमाल किया है, तो:

  1. यह तय करें कि आपको शेयर किए गए स्टोरेज के नए मॉड्यूल को कहां एलान करना है और कहां चलाना है. यहां दिए गए उदाहरण में, हमने मॉड्यूल फ़ाइल को filtering-worklet.js नाम दिया है, जो filtering-example के तहत रजिस्टर की गई है.

    (async function runFilteringIdsExample () {
  await window.sharedStorage.worklet.addModule('filtering-worklet.js');
  await window.sharedStorage.run('filtering-example', {
    keepAlive: true,
    privateAggregationConfig: {
      contextId: 'example-id',
      filteringIdMaxBytes: 8 // optional
    }
  }});
})();

    ध्यान दें कि filteringIdMaxBytes को हर रिपोर्ट के हिसाब से कॉन्फ़िगर किया जा सकता है. अगर इसे सेट नहीं किया जाता है, तो यह डिफ़ॉल्ट रूप से 1 पर सेट होता है. इस डिफ़ॉल्ट वैल्यू का मकसद, पेलोड के साइज़ को बेवजह बढ़ाने से रोकना है. इससे स्टोरेज और प्रोसेसिंग के लिए होने वाले खर्च में भी कमी आती है. ज़्यादा जानकारी के लिए, योगदान देने के लिए उपलब्ध विकल्पों के बारे में जानकारी देखें.

  2. ऊपर इस्तेमाल की गई फ़ाइल में, इस मामले में filtering-worklet.js, जब शेयर किए गए स्टोरेज वर्कलेट में privateAggregation.contributeToHistogram(...) को योगदान दिया जाता है, तो फ़िल्टर करने वाला आईडी दिया जा सकता है.

    // Within  filtering-worklet.js
class FilterOperation {
    async run() {
      let contributions = [{
        bucket: 1234n,
        value: 56,
        filteringId: 3n // defaults to 0n if not assigned, type bigint
      }];

      for (const c of contributions) {
        privateAggregation.contributeToHistogram(c);
      }
      …
  }
});

register('filtering-example', FilterOperation);

  3. एग्रीगेट की जा सकने वाली रिपोर्ट, उस एंडपॉइंट पर भेजी जाएंगी जहां आपने एंडपॉइंट /.well-known/private-aggregation/report-shared-storage तय किया है. एग्रीगेशन सेवा जॉब पैरामीटर में किए जाने वाले ज़रूरी बदलावों के बारे में जानने के लिए, आईडी फ़िल्टर करने की गाइड पर जाएं.

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

Protected Audience सेट अप करने का तरीका

अगर आपने अपने फ़्लो में Protected Audience API का इस्तेमाल किया है, तो:

  1. 'सुरक्षित ऑडियंस' को लागू करने के मौजूदा तरीके में, निजी एग्रीगेशन में शामिल करने के लिए ये सेट किए जा सकते हैं. शेयर किए गए स्टोरेज के विपरीत, फ़िल्टर करने वाले आईडी का ज़्यादा से ज़्यादा साइज़ कॉन्फ़िगर नहीं किया जा सकता. डिफ़ॉल्ट रूप से, फ़िल्टर करने वाले आईडी का ज़्यादा से ज़्यादा साइज़ 1 बाइट होता है और इसे 0n पर सेट किया जाएगा. ध्यान रखें कि ये आपके सुरक्षित ऑडियंस रिपोर्टिंग फ़ंक्शन (जैसे, reportResult() या generateBid()) में सेट किए जाएंगे.

    const contribution = {
    ...
    filteringId: 0n
};

privateAggregation.contributeToHistogram(contribution);

  2. एग्रीगेट की जा सकने वाली रिपोर्ट, उस एंडपॉइंट पर भेजी जाएंगी जहां आपने एंडपॉइंट /.well-known/private-aggregation/report-protected-audience तय किया है. बैचिंग पूरी होने और डिप्लॉय की गई एग्रीगेशन सेवा को भेजे जाने के बाद, फ़िल्टर किए गए नतीजे आपकी आखिरी खास जानकारी वाली रिपोर्ट में दिखने चाहिए. यहां Attribution Reporting API और Private Aggregation API के बारे में जानकारी देने वाले वीडियो के साथ-साथ, शुरुआती प्रस्ताव भी उपलब्ध हैं.

ज़्यादा जानकारी के लिए, एग्रीगेशन सेवा में आईडी फ़िल्टर करने की गाइड पर जाएं या Attribution Reporting API सेक्शन पर जाएं.

एग्रीगेशन सेवा

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

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

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

खास जानकारी वाली रिपोर्ट

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

खास जानकारी वाली रिपोर्ट में, की-वैल्यू पेयर का JSON डिक्शनरी स्टाइल वाला सेट होता है. हर जोड़े में ये शामिल होते हैं:

  • bucket: बाइनरी नंबर स्ट्रिंग के तौर पर एग्रीगेशन पासकोड. अगर इस्तेमाल की गई एग्रीगेशन बटन "123" है, तो बकेट "1111011" है.
  • value: किसी मेज़रमेंट लक्ष्य की खास जानकारी वाली वैल्यू, जो एग्रीगेट की जा सकने वाली सभी उपलब्ध रिपोर्ट से जोड़ी गई है.

उदाहरण के लिए:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

शोर और स्केलिंग

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

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

उदाहरण के लिए, मान लें कि नॉइज़ डिस्ट्रिब्यूशन का स्टैंडर्ड डेविएशन 100 है और यह शून्य पर केंद्रित है. अगर इकट्ठा की गई एग्रीगेट की जा सकने वाली रिपोर्ट वैल्यू (या "एग्रीगेट की जा सकने वाली वैल्यू") सिर्फ़ 200 है, तो गड़बड़ी का स्टैंडर्ड डेविएशन, एग्रीगेट की गई वैल्यू का 50% होगा. हालांकि, अगर एग्रीगेट की जा सकने वाली वैल्यू 20,000 है, तो गड़बड़ी का स्टैंडर्ड डेविएशन, एग्रीगेट की गई वैल्यू का सिर्फ़ 0.5% होगा. इसलिए, 20,000 की एग्रीगेट की जा सकने वाली वैल्यू का सिग्नल-शोर अनुपात बहुत ज़्यादा होगा.

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

एग्रीगेट की गई वैल्यू के बावजूद, नॉइज़ एक जैसा रहता है.

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

एग्रीगेट की जा सकने वाली वैल्यू को योगदान बजट पर स्केल करें.

स्केलिंग फ़ैक्टर का सही हिसाब लगाने के लिए, योगदान के बजट को सभी बटन के लिए एग्रीगेट की जा सकने वाली वैल्यू के सबसे बड़े योग से भाग दें.

ज़्यादा जानने के लिए, योगदान के बजट से जुड़ा दस्तावेज़ देखें.

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

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