Private एग्रीगेशन API के मुख्य कॉन्सेप्ट
यह दस्तावेज़ किसके लिए है?
निजी एग्रीगेशन एपीआई क्रॉस-साइट डेटा के ऐक्सेस वाले वर्कलेट से एग्रीगेट डेटा कलेक्शन को चालू करता है. यहां शेयर किए गए कॉन्सेप्ट, रिपोर्टिंग बनाने वाले डेवलपर के लिए ज़रूरी हैं शेयर किए गए स्टोरेज और Protected Audience API के अंदर मौजूद फ़ंक्शन.
- अगर आप कोई डेवलपर हैं और क्रॉस-साइट के लिए रिपोर्टिंग सिस्टम बना रहे हैं और उन्हें मापा जा सकता है.
- अगर आप मार्केटर, डेटा साइंटिस्ट या खास जानकारी वाली रिपोर्ट हैं उपभोक्ता, इन प्रक्रियाओं को समझने से आपको अपने संगठन के लिए फ़ैसले के तहत, ऑप्टिमाइज़ की गई खास जानकारी वाली रिपोर्ट को फिर से हासिल किया जा सकता है.
मुख्य शब्द
इस दस्तावेज़ को पढ़ने से पहले, इसके बारे में जान लें इस्तेमाल करते हैं. यहां इन सभी शब्दों के बारे में पूरी जानकारी दी गई है.
- एग्रीगेशन पासकोड (जिसे बकेट भी कहा जाता है) पहले से तय डेटा पॉइंट इकट्ठा करना. उदाहरण के लिए, हो सकता है कि आप जहां ब्राउज़र देश की रिपोर्ट करता है, वहां जगह की जानकारी के डेटा का बकेट इकट्ठा करें नाम. किसी एग्रीगेशन कुंजी में एक से ज़्यादा डाइमेंशन हो सकते हैं (उदाहरण के लिए, देश और आपके कॉन्टेंट के विजेट का आईडी).
- एग्रीगेट की जा सकने वाली वैल्यू, एक निजी डेटा पॉइंट होता है
को एग्रीगेशन कुंजी में इकट्ठा किया जा सकता है. अगर आपको यह मेज़र करना है कि कितने उपयोगकर्ताओं ने
फ़्रांस के लोगों ने आपका कॉन्टेंट देखा है. इसलिए,
France
एग्रीगेशन कुंजी होती है और1
काviewCount
एग्रीगेट की जा सकने वाली वैल्यू होती है. - एग्रीगेट की जा सकने वाली रिपोर्ट, ब्राउज़र में जनरेट और एन्क्रिप्ट (सुरक्षित) की जाती हैं. निजी एग्रीगेशन एपीआई, इसमें किसी एक इवेंट का डेटा शामिल होता है.
- एग्रीगेशन सेवा खास जानकारी वाली रिपोर्ट बनाने के लिए, एग्रीगेट की जा सकने वाली रिपोर्ट के डेटा को प्रोसेस करता है.
- खास जानकारी वाली रिपोर्ट, एग्रीगेशन सेवा का फ़ाइनल आउटपुट होती है और इसमें ग़ैर-ज़रूरी उपयोगकर्ताओं का एग्रीगेट किया गया डेटा और ज़्यादा जानकारी वाला कन्वर्ज़न डेटा शामिल है.
- वर्कलेट एक टुकड़ा होता है एक ऐसी बुनियादी संरचना है जो आपको विशिष्ट JavaScript फ़ंक्शन चलाने और अनुरोधकर्ता को जानकारी वापस लौटाएं. वर्कलेट में, JavaScript का इस्तेमाल करें, लेकिन बाहरी पेज से इंटरैक्ट या इंटरैक्ट नहीं किया जा सकता.
निजी एग्रीगेशन वर्कफ़्लो
जब आप निजी एग्रीगेशन एपीआई को किसी एग्रीगेशन कुंजी और जब ब्राउज़र, एग्रीगेट की जा सकने वाली रिपोर्ट जनरेट करता है. रिपोर्ट आपके सर्वर पर भेजे जाते हैं, जो रिपोर्ट के बैच बनाते हैं. बैच में बनाई गई रिपोर्ट एग्रीगेशन सेवा के ज़रिए प्रोसेस किया जाता है और खास जानकारी वाली रिपोर्ट जनरेट की जाती है.
- निजी एग्रीगेशन एपीआई को कॉल करने पर, क्लाइंट (ब्राउज़र) आपकी साइट के लिए और इकट्ठा करने के लिए आपके सर्वर पर एग्रीगेट की जा सकने वाली रिपोर्ट भेजता है.
- आपका सर्वर क्लाइंट से रिपोर्ट इकट्ठा करता है और उन्हें एक को एग्रीगेशन सेवा को भेजा गया.
- पर्याप्त रिपोर्ट इकट्ठा कर लेने के बाद, आप उन्हें बैच बनाकर एग्रीगेशन सेवा, जो भरोसेमंद एक्ज़ीक्यूशन एनवायरमेंट में चल रही है. इससे ये जनरेट किए जा सकते हैं खास जानकारी वाली रिपोर्ट में.
इस सेक्शन में बताया गया वर्कफ़्लो, एट्रिब्यूशन रिपोर्टिंग की तरह है एपीआई. हालांकि, एट्रिब्यूशन रिपोर्टिंग, इंप्रेशन इवेंट और कन्वर्ज़न से इकट्ठा किए गए डेटा को जोड़ती है जो अलग-अलग समय पर हों. प्राइवेट एग्रीगेशन किसी सिंगल, क्रॉस-साइट इवेंट.
एग्रीगेशन कुंजी
एग्रीगेशन की (कम शब्दों में "कुंजी") उस बकेट के बारे में बताती है जहां एग्रीगेट की जा सकने वाली वैल्यू इकट्ठा हो जाएंगी. एक या उससे ज़्यादा डाइमेंशन को कोड में बदला जा सकता है किया जा सकता है. डाइमेंशन किसी ऐसे पहलू को दिखाता है जिसमें आपको ज़्यादा फ़ायदा पाना है के बारे में अहम जानकारी, जैसे कि उपयोगकर्ताओं के उम्र समूह या किसी विज्ञापन के इंप्रेशन की संख्या कैंपेन बनाएं.
उदाहरण के लिए, आपके पास ऐसा विजेट हो सकता है जिसे कई साइटों और उन उपयोगकर्ताओं के देश का विश्लेषण करना चाहते हैं जिन्होंने आपका विजेट देखा है. आप देख रहे हैं का जवाब देने के लिए, जैसे कि "मेरा विजेट देखने वाले कितने उपयोगकर्ता हैं देश X से?" इस सवाल की रिपोर्ट पाने के लिए, एग्रीगेशन कुंजी को सेट अप किया जा सकता है जो दो डाइमेंशन को कोड में बदलता है: विजेट आईडी और देश आईडी.
निजी एग्रीगेशन एपीआई को दी गई कुंजी यह है
BigInt,
जिसमें कई डाइमेंशन होते हैं. इस उदाहरण में, डाइमेंशन
विजेट आईडी और देश आईडी. मान लें कि विजेट आईडी ज़्यादा से ज़्यादा चार अंकों का हो सकता है
जैसे, 1234
, और हर देश को वर्णमाला के क्रम में किसी संख्या से मैप किया जाता है
क्रम में अफ़ग़ानिस्तान 1
, फ़्रांस 61
, और ज़िंबाब्वे '195' है.
इसलिए, इकट्ठा की जा सकने वाली कुंजी सात अंकों की होगी, जिसमें पहले चार
वर्ण WidgetID
के लिए आरक्षित हैं और अंतिम 3 वर्ण हैं
CountryID
के लिए बुक किया गया.
मान लें कि यह कुंजी, फ़्रांस के उपयोगकर्ताओं की संख्या (देश आईडी 061
) के बारे में बताती है
जिन लोगों ने विजेट आईडी 3276
देखा है, एग्रीगेशन कुंजी 3276061
है.
एग्रीगेशन कुंजी | |
विजेट आईडी | देश का आईडी |
3276 | 061 |
एग्रीगेशन कुंजी को हैशिंग मैकेनिज़्म की मदद से भी जनरेट किया जा सकता है. जैसे
SHA-256. उदाहरण के लिए,
{"WidgetId":3276,"CountryID":67}
को हैश करके इसे इसमें बदला जा सकता है
BigInt
का मान
42943797454801331377966796057547478208888578253058197330928948081739249096287n
.
अगर हैश वैल्यू में 128 से ज़्यादा बिट हैं, तो इसे छोटा किया जा सकता है, ताकि यह पक्का हो सके कि
2^128−1
कीअधिकतमस्वीकृत बकेट मान से ज़्यादा है.
Shared Storage के वर्कलेट में, आप
crypto
और
TextEncoder
मॉड्यूल
जिसकी मदद से हैश जनरेट किया जा सकता है. हैश जनरेट करने के बारे में ज़्यादा जानने के लिए, यहां जाएं
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 देखने वाले करीब 4881 उपयोगकर्ताओं ने फ़्रांस से." हर उपयोगकर्ता के लिए एग्रीगेट की जा सकने वाली वैल्यू 1 है और "4881 उपयोगकर्ता" है इससे मेल खाता है एग्रीगेट की गई वैल्यू, जो उस वैल्यू के लिए सभी एग्रीगेट की जा सकने वाली वैल्यू का योग होती है एग्रीगेशन कुंजी.
एग्रीगेशन कुंजी | एग्रीगेट की जा सकने वाली वैल्यू | |
विजेट आईडी | देश का आईडी | देखे जाने की संख्या |
3276 | 061 | 1 |
उदाहरण के लिए, हम बैज देखने वाले हर उपयोगकर्ता के लिए वैल्यू में 1 की बढ़ोतरी करते हैं. व्यावहारिक तौर पर, सिग्नल-टू-नॉइज़ को बेहतर बनाने के लिए, इकट्ठा की जा सकने वाली वैल्यू को बढ़ाया जा सकता है अनुपात.
योगदान का बजट
Private एग्रीगेशन API के लिए किए जाने वाले हर कॉल को योगदान कहा जाता है. सुरक्षित करने के लिए उपयोगकर्ता की निजता, योगदानों की वह संख्या जो एक व्यक्तिगत आय सीमित हैं.
जब एग्रीगेशन कुंजियों में मौजूद सभी एग्रीगेट की जा सकने वाली वैल्यू को जोड़ा जाता है, तो कुल योग में योगदान के बजट से कम होगा. बजट का दायरा हर वर्कलेट के हिसाब से है शुरुआत की जगह, हर दिन, और यह है Protected Audience API और Shared Storage के वर्कलेट के लिए अलग-अलग है. रोलिंग दिन के लिए करीब पिछले 24 घंटे की विंडो का इस्तेमाल किया जाता है. अगर नए एग्रीगेट करने लायक रिपोर्ट से बजट की सीमा बढ़ जाएगी, लेकिन रिपोर्ट बनाया गया.
योगदान के लिए बजट पैरामीटर L1 से दिखाया जाता है. 220 के बैकस्टॉप के साथ, हर दिन हर 10 मिनट के लिए 16 (65,536) पर सेट किया गया
(10,48,576). ज़्यादा जानकारी के लिए, जानकारी देने वाला से इन पैरामीटर के बारे में ज़्यादा जानें.
योगदान के बजट की वैल्यू मनमुताबिक है, लेकिन शोर को उसके हिसाब से बढ़ाया गया है. इस बजट का इस्तेमाल, खास जानकारी वाली वैल्यू पर सिग्नल-टू-नॉइज़ रेशियो को बढ़ाने के लिए किया जा सकता है (इसकी ज़्यादा जानकारी शोर और स्केलिंग सेक्शन में दी गई है).
योगदान के लिए बजट के बारे में ज़्यादा जानने के लिए, जानकारी देने वाला. साथ ही, योगदान देने वाला सेक्शन देखें बजट की मदद ली जा सकती है.
इकट्ठा की जा सकने वाली रिपोर्ट
जब उपयोगकर्ता Private एग्रीगेशन एपीआई को शुरू करता है, तो ब्राउज़र जनरेट करता है
इकट्ठा की जा सकने वाली रिपोर्ट को एग्रीगेशन सेवा बाद में प्रोसेस करेगी
खास जानकारी को जनरेट करने में लगने वाला समय
रिपोर्ट. अगर आप
इकट्ठा की जा सकने वाली रिपोर्ट, 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 एग्रीगेशन एपीआई को कॉल किया गया है पथ:
- शेयर किए गए स्टोरेज के लिए:
/.well-known/private-aggregation/report-shared-storage
- सुरक्षित ऑडियंस के लिए:
/.well-known/private-aggregation/report-protected-audience
अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है
इन एंडपॉइंट पर, आपको एक सर्वर ऑपरेट करना होगा. यह कलेक्टर के तौर पर काम करता है जिसे क्लाइंट से भेजी गई एग्रीगेट की जा सकने वाली रिपोर्ट मिलती हैं.
इसके बाद सर्वर को रिपोर्ट बैच बनाना चाहिए और बैच को एग्रीगेशन में भेजना चाहिए
सेवा. एन्क्रिप्ट न की गई जानकारी के आधार पर बैच बनाएं
एग्रीगेट की जा सकने वाली रिपोर्ट का पेलोड, जैसे कि shared_info
फ़ील्ड. आम तौर पर,
बैच में हर बैच के लिए 100 या उससे ज़्यादा रिपोर्ट होनी चाहिए.
आपके पास रोज़ या हर हफ़्ते के हिसाब से बैच बनाने का विकल्प है. इस रणनीति में ज़रूरत के हिसाब से बदलाव किए जा सकते हैं. साथ ही, खास इवेंट के लिए एक साथ कई अनुरोध करने की रणनीति में बदलाव किया जा सकता है. ज़्यादा वॉल्यूम—उदाहरण के लिए, साल के वे दिन जब ज़्यादा इंप्रेशन मिलने की उम्मीद हो. बैच में एक जैसे एपीआई वर्शन, रिपोर्टिंग ऑरिजिन, और रिपोर्ट का समय शेड्यूल करें.
एग्रीगेशन सेवा
एग्रीगेशन सेवा कलेक्टर से एन्क्रिप्ट (सुरक्षित) की गई एग्रीगेट की जा सकने वाली रिपोर्ट हासिल करता है और खास जानकारी जनरेट करता है रिपोर्ट.
रिपोर्ट के पेलोड को डिक्रिप्ट करने के लिए, एग्रीगेशन सेवा एक डिक्रिप्शन कुंजी फ़ेच करती है कोऑर्डिनेटर से मिलता है. सेवा, भरोसेमंद एक्ज़ीक्यूशन एनवायरमेंट (टीईई) में चलती है, इससे डेटा के रखरखाव, डेटा की गोपनीयता, और और कोड इंटेग्रिटी प्रोटेक्शन की सुविधा उपलब्ध है. भले ही आप सेवा के मालिक हैं और इसे चलाते हैं, लेकिन आपके पास टीईई में प्रोसेस हो रहे डेटा को देखने की क्षमता को दिखाता है.
खास जानकारी वाली रिपोर्ट
खास जानकारी वाली रिपोर्ट इससे आपको अतिरिक्त ग़ैर-ज़रूरी डेटा इकट्ठा करने की सुविधा मिलती है. आप इसका अनुरोध कर सकते हैं कुंजियों के सेट की खास जानकारी वाली रिपोर्ट.
खास जानकारी वाली रिपोर्ट में, की-वैल्यू पेयर का 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 एग्रीगेशन एपीआई पर चर्चा जारी है. इसमें बदलाव हो सकता है आने वाले समय में. अगर आपने इस एपीआई को आज़माया है और आपके पास कोई सुझाव है, तो हमें ज़रूर बताएं.
- GitHub: पढ़ें जानकारी देने वाला, सवाल पूछें और इनमें हिस्सा लें चर्चा. * डेवलपर सहायता: Privacy Sandbox के लिए डेवलपर सहायता टीम रेपो के बारे में ज़्यादा जानें. * Shared Storage API में शामिल हों ग्रुप और Protected Audience API ग्रुप प्राइवेट एग्रीगेशन से जुड़ी नई सूचनाओं के लिए.