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

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

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

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

Shared Storage API

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

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

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

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

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

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

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

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

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

JavaScript की तरह ही, रिस्पॉन्स हेडर का इस्तेमाल करके, शेयर किए गए स्टोरेज में वैल्यू सेट करने, जोड़ने, और मिटाने जैसे खास फ़ंक्शन ही किए जा सकते हैं. रिस्पॉन्स हेडर में, Shared Storage के साथ काम करने के लिए, अनुरोध हेडर में 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 टैग के साथ IDL एट्रिब्यूट का इस्तेमाल करना
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

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

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

Shared Storage में डेटा लिखने के लिए, 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');

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

शेयर किए गए स्टोरेज से आइटम मिटाया जा रहा है

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

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

वर्कलेट के बाहर से Shared Storage से फ़ाइल मिटाने के लिए:
```
window.sharedStorage.delete('myKey');
```
वर्कलेट में जाकर, Shared Storage से फ़ाइल मिटाने के लिए:
```
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 के ऑरिजिन के शेयर किए गए स्टोरेज में सेव करता है.

पहले पक्ष का कॉन्टेक्स्ट

अगर किसी पहले पक्ष के पेज में तीसरे पक्ष का ऐसा JavaScript कोड जोड़ा गया है जो sharedStorage.set() या sharedStorage.delete() को कॉल करता है, तो कुंजी-वैल्यू पेयर को पहले पक्ष के संदर्भ में सेव किया जाता है.

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

तीसरे पक्ष का कॉन्टेक्स्ट

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

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

Private Aggregation API

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

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

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

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

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

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

शेयर किए गए स्टोरेज से डेटा ऐक्सेस करने के लिए, आपको वर्कलेट बनाना होगा. ऐसा करने के लिए, वर्कलेट के यूआरएल के साथ createWorklet() को कॉल करें. डिफ़ॉल्ट रूप से, createWorklet() के साथ शेयर किए गए स्टोरेज का इस्तेमाल करने पर, डेटा सेक्शन का ऑरिजिन, ब्राउज़िंग कॉन्टेक्स्ट का ऑरिजिन होगा, न कि वर्कलेट स्क्रिप्ट का ऑरिजिन.

डिफ़ॉल्ट तरीके को बदलने के लिए, createWorklet को कॉल करते समय dataOrigin प्रॉपर्टी सेट करें.

dataOrigin: "context-origin": (डिफ़ॉल्ट) डेटा, ब्राउज़िंग कॉन्टेक्स्ट को ट्रिगर करने वाले ऑरिजिन के शेयर किए गए स्टोरेज में सेव किया जाता है.
dataOrigin: "script-origin": डेटा को वर्कलेट स्क्रिप्ट के ऑरिजिन के शेयर किए गए स्टोरेज में सेव किया जाता है. ध्यान दें कि इस मोड को चालू करने के लिए ऑप्ट-इन करना ज़रूरी है.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

"script-origin" का इस्तेमाल करते समय, ऑप्ट-इन करने के लिए स्क्रिप्ट एंडपॉइंट को हेडर Shared-Storage-Cross-Origin-Worklet-Allowed के साथ रिस्पॉन्स देना होगा. ध्यान दें कि क्रॉस-ऑरिजिन अनुरोधों के लिए, CORS चालू होना चाहिए.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

क्रॉस-ऑरिजिन iframe का इस्तेमाल करना

शेयर किए गए स्टोरेज के वर्कलेट को चालू करने के लिए, iframe की ज़रूरत होती है.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

वर्कलेट स्क्रिप्ट में, आपको एक ऐसी क्लास बनानी होगी जिसमें एक साथ कई काम करने की सुविधा वाला run तरीका और register विज्ञापन के iframe में चलाने के लिए, उसे शामिल करना होगा. अंदर का हिस्सा sharedStorageWorklet.js:

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

अलग-अलग डोमेन से अनुरोध करने की सुविधा का इस्तेमाल करना

शेयर किए गए स्टोरेज और निजी एग्रीगेशन की मदद से, क्रॉस-ऑरिजिन iframe के बिना क्रॉस-ऑरिजिन वर्कलेट बनाए जा सकते हैं.

पहले पक्ष का पेज भी क्रॉस-ऑरिजिन JavaScript एंडपॉइंट पर createWorklet() कॉल शुरू कर सकता है. वर्कलेट बनाते समय, आपको वर्कलेट के डेटा सेगमेंट के ऑरिजिन को स्क्रिप्ट के ऑरिजिन के तौर पर सेट करना होगा.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

क्रॉस-ऑरिजिन JavaScript एंडपॉइंट को Shared-Storage-Cross-Origin-Worklet-Allowed हेडर के साथ जवाब देना होगा. साथ ही, ध्यान रखें कि इस अनुरोध के लिए सीओआरएस चालू है.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

createWorklet() का इस्तेमाल करके बनाए गए वर्कलेट में selectURL और run() होंगे. इसके लिए, addModule() उपलब्ध नहीं है.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

अगले चरण

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

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

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

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

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

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