इस पेज का अनुवाद Cloud Translation API से किया गया है.

शेयर किए गए स्टोरेज और निजी एग्रीगेशन को लागू करने के लिए क्विकस्टार्ट

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

टारगेट ऑडियंस: विज्ञापन टेक्नोलॉजी और मेज़रमेंट की सुविधा देने वाली कंपनियां.

डेमो आज़माएं

लाइव डेमो देखें. Privacy Sandbox API को चालू करने के लिए, डेमो निर्देशों में दिए गए निर्देशों का पालन करें. Chrome DevTools खोलने पर, इस्तेमाल के अलग-अलग उदाहरणों से मिले नतीजों को विज़ुअलाइज़ करने में मदद मिलती है. डेमो में दिए गए इस्तेमाल के उदाहरण:

निजी एग्रीगेशन
- यूनीक रीच का मेज़रमेंट
- डेमोग्राफ़िक्स मेज़रमेंट
- K+ फ़्रीक्वेंसी मेज़रमेंट
सामान्य इस्तेमाल
- फ़ेंस किए गए फ़्रेम में कर्सर घुमाने पर होने वाले इवेंट को मेज़र करें
- टॉप-लेवल नेविगेशन
- यह तय करना कि तीसरे पक्ष, किन लेखों में बदलाव कर सकते हैं

शेयर किया गया स्टोरेज देखने का तरीका

शेयर किए गए स्टोरेज में क्या सेव किया गया है, यह देखने के लिए Chrome DevTools का इस्तेमाल करें. सेव किया गया डेटा, Application -> Shared Storage में मिल सकता है.

Chrome DevTools का इस्तेमाल करके, शेयर किए गए स्टोरेज में सेव किया गया डेटा देखें.

निजी एग्रीगेशन की रिपोर्ट देखें

भेजी गई इकट्ठा की जा सकने वाली रिपोर्ट देखने के लिए, chrome://private-aggregation-internals पर जाएं. डीबग मोड चालू होने पर, [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage को एक रिपोर्ट तुरंत (बिना किसी देरी के) भेजी जाती है. साथ ही, तय समय में [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage को भेजी जाने वाली रिपोर्ट भी भेजी जाती है.

डीबग करने की सुविधा चालू करने के लिए, डीबग करना सेक्शन में दिए गए निर्देशों का पालन करें.

chrome://private-aggregation-internals में रिपोर्ट देखना.

Shared Storage API

क्रॉस-साइट ट्रैकिंग को रोकने के लिए, ब्राउज़र ने डिवाइस के स्टोरेज, कुकी वगैरह के साथ-साथ सभी तरह के स्टोरेज को अलग-अलग हिस्सों में बांटना शुरू कर दिया है. हालांकि, कुछ मामलों में अलग से स्टोरेज की ज़रूरत भी होती है. Shared Storage API, निजता को बनाए रखते हुए, पढ़ने का ऐक्सेस देता है. साथ ही, इससे टॉप लेवल की अलग-अलग साइटों पर, कॉन्टेंट लिखने का अनलिमिटेड ऐक्सेस मिलता है.

शेयर किए गए स्टोरेज की जगह, कॉन्टेक्स्ट ऑरिजिन (sharedStorage का कॉलर) तक सीमित है.

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

शेयर किए गए स्टोरेज की सुविधा शुरू करना

विज्ञापन टेक्नोलॉजी, JavaScript या रिस्पॉन्स हेडर का इस्तेमाल करके शेयर किए गए स्टोरेज में डेटा लिख सकती हैं. शेयर किए गए स्टोरेज से डेटा पढ़ना सिर्फ़ एक अलग JavaScript एनवायरमेंट में होता है, जिसे वर्कलेट कहा जाता है.

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

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

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

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

यह सुविधा M119 में उपलब्ध हुई थी.

JavaScript की तरह ही, शेयर किए गए स्टोरेज में वैल्यू सेट करने, जोड़ने, और मिटाने जैसे कुछ खास फ़ंक्शन ही रिस्पॉन्स हेडर इस्तेमाल करके किए जा सकते हैं. रिस्पॉन्स हेडर में, शेयर किए गए स्टोरेज का इस्तेमाल करने के लिए, Shared-Storage-Writable: ?1 को अनुरोध के हेडर में शामिल करना ज़रूरी है.

क्लाइंट से अनुरोध करने के लिए, अपने चुने गए तरीके के आधार पर नीचे दिया गया कोड चलाएं:
- fetch() का इस्तेमाल करना
```
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
```
- iframe या img टैग का इस्तेमाल करना
```
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
```
- iframe या img टैग के साथ आईडीएल एट्रिब्यूट का इस्तेमाल करना
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

ज़्यादा जानकारी के लिए, शेयर किया गया स्टोरेज: रिस्पॉन्स हेडर पर जाएं.

शेयर किए गए स्टोरेज में लिखना

शेयर किए गए स्टोरेज में लिखने के लिए, JavaScript वर्कलेट में या उसके बाहर sharedStorage.set() पर कॉल करें. वर्कलेट के बाहर से कॉल करने पर, डेटा को ब्राउज़िंग कॉन्टेक्स्ट के ऑरिजिन के हिसाब से लिखा जाता है. इससे, कॉल करने में मदद मिलती है. अगर वर्कलेट में से कॉल किया जाता है, तो डेटा को वर्कलेट लोड करने वाले ब्राउज़िंग कॉन्टेक्स्ट के ऑरिजिन पर लिखा जाता है. सेट की गई कुंजियों की समयसीमा खत्म होने की तारीख, आखिरी बार अपडेट किए जाने के 30 दिनों के बाद होती है.

ignoreIfPresent फ़ील्ड ज़रूरी नहीं है. अगर यह मौजूद है और true पर सेट है, तो अगर कुंजी पहले से मौजूद है, तो इसे अपडेट नहीं किया जाता. कुंजी की समयसीमा खत्म होने की तारीख, set() कॉल के 30 दिनों के बाद रिन्यू होती है. ऐसा तब भी होता है, जब कुंजी अपडेट न की गई हो.

अगर शेयर किए गए स्टोरेज को एक ही कुंजी से एक ही पेज लोड में कई बार ऐक्सेस किया जाता है, तो कुंजी का मान ओवरराइट हो जाता है. अगर कुंजी को पिछली वैल्यू को बनाए रखने की ज़रूरत है, तो sharedStorage.append() का इस्तेमाल करना बेहतर होगा.

JavaScript का इस्तेमाल करना

वर्कलेट के बाहर:

window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
// Shared Storage: {'myKey': 'myValue2'}

इसी तरह, वर्कलेट के अंदर:

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

रिस्पॉन्स हेडर का इस्तेमाल करना

रिस्पॉन्स हेडर का इस्तेमाल करके भी, शेयर किए गए स्टोरेज में सेव किया जा सकता है. ऐसा करने के लिए, रिस्पॉन्स हेडर में इन निर्देशों के साथ Shared-Storage-Write का इस्तेमाल करें:
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
```
एक से ज़्यादा आइटम को कॉमा लगाकर अलग किया जा सकता है और set, append, delete, और clear को जोड़ा जा सकता है.
```
Shared-Storage-Write : 
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
```

वैल्यू जोड़ना

किसी मौजूदा कुंजी में, 'जोड़ें' तरीके का इस्तेमाल करके वैल्यू जोड़ी जा सकती है. अगर कुंजी मौजूद नहीं है, तो append() को कॉल करने से कुंजी बन जाती है और वैल्यू सेट हो जाती है. JavaScript या रिस्पॉन्स हेडर का इस्तेमाल करके ऐसा किया जा सकता है.

JavaScript का इस्तेमाल करना

मौजूदा कुंजियों की वैल्यू अपडेट करने के लिए, वर्कलेट के अंदर या बाहर sharedStorage.append() का इस्तेमाल करें.
```
window.sharedStorage.append('myKey', 'myValue1');
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.append('myKey', 'myValue2');
// Shared Storage: {'myKey': 'myValue1myValue2'}
window.sharedStorage.append('anotherKey', 'hello');
// Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
```
वर्कलेट में जोड़ने के लिए:
```
sharedStorage.append('myKey', 'myValue1');
```
रिस्पॉन्स हेडर का इस्तेमाल करना

शेयर किए गए स्टोरेज में कोई वैल्यू सेट करने की तरह ही, की-वैल्यू पेयर को पास करने के लिए, रिस्पॉन्स हेडर में Shared-Storage-Write का इस्तेमाल किया जा सकता है.
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

शेयर किए गए स्टोरेज से पढ़ना

शेयर किए गए स्टोरेज से, सिर्फ़ वर्कलेट में से डेटा पढ़ा जा सकता है.

await sharedStorage.get('mykey');

वर्कलेट मॉड्यूल को लोड किए गए ब्राउज़िंग कॉन्टेक्स्ट के ऑरिजिन से यह तय होता है कि शेयर किए गए स्टोरेज का डेटा किसका है.

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

वर्कलेट के अंदर या बाहर JavaScript का इस्तेमाल करके, शेयर किए गए स्टोरेज से आइटम मिटाए जा सकते हैं. इसके अलावा, delete() के साथ रिस्पॉन्स हेडर का इस्तेमाल करके भी ये आइटम मिटाए जा सकते हैं. एक साथ सभी बटन मिटाने के लिए, इनमें से किसी भी बटन से clear() का इस्तेमाल करें.

JavaScript का इस्तेमाल करना

वर्कलेट के बाहर से शेयर किए गए स्टोरेज से मिटाने के लिए:
```
window.sharedStorage.delete('myKey');
```
वर्कलेट में जाकर, शेयर किए गए स्टोरेज से डेटा मिटाने के लिए:
```
sharedStorage.delete('myKey');
```
वर्कलेट के बाहर मौजूद सभी कुंजियों को एक साथ मिटाने के लिए:
```
window.sharedStorage.clear();
```
वर्कलेट में से सभी कुंजियों को एक साथ मिटाने के लिए:
```
sharedStorage.clear();
```
रिस्पॉन्स हेडर का इस्तेमाल करना

रिस्पॉन्स हेडर का इस्तेमाल करके वैल्यू मिटाने के लिए, रिस्पॉन्स हेडर में Shared-Storage-Write का इस्तेमाल करके भी, मिटाई जाने वाली कुंजी को पास किया जा सकता है.
```
delete;key="myKey"
```
रिस्पॉन्स हेडर का इस्तेमाल करके सभी कुंजियां मिटाने के लिए:
```
clear;
```

संदर्भ स्विच करना

शेयर किए गए स्टोरेज का डेटा, उस ब्राउज़िंग कॉन्टेक्स्ट के ऑरिजिन (उदाहरण के लिए, https://example.adtech.com) पर लिखा जाता है जिससे कॉल किया गया है.

जब <script> टैग का इस्तेमाल करके तीसरे पक्ष का कोड लोड किया जाता है, तो कोड को एम्बेडर के ब्राउज़िंग कॉन्टेक्स्ट में चलाया जाता है. इसलिए, जब तीसरे पक्ष का कोड sharedStorage.set() को कॉल करता है, तो डेटा को एम्बेड करने वाले व्यक्ति के शेयर किए गए स्टोरेज में सेव किया जाता है. जब किसी iframe में तीसरे पक्ष का कोड लोड किया जाता है, तो कोड को एक नया ब्राउज़िंग कॉन्टेक्स्ट मिलता है. साथ ही, इसका ऑरिजिन, iframe का ऑरिजिन होता है. इसलिए, iframe से किया गया sharedStorage.set() कॉल, डेटा को iframe ऑरिजिन के शेयर किए गए स्टोरेज में सेव करता है.

पहले पक्ष की जानकारी

अगर पहले पक्ष के किसी पेज पर, sharedStorage.set() या sharedStorage.delete() को कॉल करने वाला, तीसरे पक्ष का JavaScript कोड एम्बेड किया गया है, तो की-वैल्यू पेयर को पहले पक्ष के कॉन्टेक्स्ट में सेव किया जाता है.

एम्बेड किए गए तीसरे पक्ष की JavaScript के साथ, पहले पक्ष के पेज में स्टोर किया गया डेटा.

तीसरे पक्ष का संदर्भ

की-वैल्यू पेयर को विज्ञापन टेक्नोलॉजी या तीसरे पक्ष के कॉन्टेक्स्ट में सेव किया जा सकता है. इसके लिए, आपको iframe बनाना होगा और iframe से JavaScript कोड में set() या delete() को कॉल करना होगा.

विज्ञापन टेक्नोलॉजी या तीसरे पक्ष के कॉन्टेक्स्ट में सेव किया गया डेटा.

निजी एग्रीगेशन एपीआई

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

रिपोर्ट बनाने के लिए, बकेट और वैल्यू वाले वर्कलेट में contributeToHistogram() को कॉल करें. बकेट को साइन न किए गए 128-बिट वाले पूर्णांक से दिखाया जाता है. इसे फ़ंक्शन में BigInt के तौर पर पास किया जाना चाहिए. वैल्यू एक पॉज़िटिव पूर्णांक है.

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

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

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

शेयर किए गए स्टोरेज और निजी डेटा इकट्ठा करना

विज्ञापन के iframe में, addModule() को कॉल करके वर्कलेट मॉड्यूल लोड करें. sharedStorageWorklet.js वर्कलेट फ़ाइल में रजिस्टर किए गए तरीके को चलाने के लिए, उसी विज्ञापन iframe JavaScript में, sharedStorage.run() को कॉल करें.

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

वर्कलेट स्क्रिप्ट में, आपको एक साथ काम नहीं करने वाले run तरीके का इस्तेमाल करके क्लास बनानी होगी. और विज्ञापन के iframe में चलने के लिए इस क्लास को register करें. sharedStorageWorklet.js में:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

डीबग करना

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

privateAggregation.enableDebugMode();

रिपोर्ट को ट्रिगर करने वाले कॉन्टेक्स्ट से जोड़ने के लिए, 64-बिट की बिना हस्ताक्षर वाले पूर्णांक को डीबग करने की कुंजी सेट की जा सकती है. इसे JavaScript कॉल को भेजा जाता है. debugKey एक BigInt है.

privateAggregation.enableDebugMode({debugKey: 1234});

शेयर किए गए स्टोरेज को डीबग करना

शेयर किए गए स्टोरेज की मदद से, गड़बड़ी का यह सामान्य मैसेज मिलता है:

Promise is rejected without and explicit error message

कॉल को try-catch ब्लॉक के साथ रैप करके, शेयर किए गए स्टोरेज को डीबग किया जा सकता है.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

निजी एग्रीगेशन को डीबग करना

रिपोर्ट /.well-known/private-aggregation/report-shared-storage और /.well-known/private-aggregation/debug/report-shared-storage पर भेजी जाती हैं. डीबग रिपोर्ट को नीचे दिए गए JSON जैसा पेलोड मिलता है. यह पेलोड api फ़ील्ड को "शेयर किए गए स्टोरेज" के तौर पर बताता है.

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

साफ़ टेक्स्ट पेलोड को डीबग करें

debug_cleartext_payload को Base64 CBOR-कोड में बदला गया है. डीकोडर का इस्तेमाल करके, बकेट और वैल्यू देखी जा सकती है या शेयर किए गए स्टोरेज डिकोडर में मौजूद JavaScript कोड का इस्तेमाल किया जा सकता है.

अगले चरण

नीचे दिए गए पेजों पर, शेयर किए गए स्टोरेज और निजी एग्रीगेशन एपीआई के अहम पहलुओं के बारे में बताया गया है.

एपीआई के बारे में जानने के बाद, रिपोर्ट इकट्ठा करना शुरू किया जा सकता है. ये रिपोर्ट, अनुरोध के मुख्य हिस्से में JSON के तौर पर, पोस्ट अनुरोध के तौर पर इन एंडपॉइंट को भेजी जाती हैं.

डीबग रिपोर्ट - context-origin/.well-known/private-aggregation/debug/report-shared-storage
रिपोर्ट - context-origin/.well-known/private-aggregation/report-shared-storage

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

सुझाव/राय दें या शिकायत करें

GitHub पर एपीआई और दस्तावेज़ के बारे में अपनी राय दें.