Privacy Sandbox की कुछ टेक्नोलॉजी को बंद किया जा रहा है.

Privacy Sandbox की टेक्नोलॉजी के लिए प्लान से जुड़ा हमारा अपडेट देखें.

Privacy Sandbox की सुविधा की स्थिति से, अलग-अलग एपीआई और प्लैटफ़ॉर्म की सुविधाओं की स्थिति के बारे में ज़्यादा जानकारी मिलती है.

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

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

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

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

Shared Storage API

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

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

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

Shared Storage को चालू करना

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

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

Shared Storage में डेटा लिखना

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 में लिखा जा सकता है. इसके लिए, जवाब के हेडर में 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 तरीके का इस्तेमाल करके, किसी मौजूदा कुंजी में वैल्यू जोड़ी जा सकती है. अगर कुंजी मौजूद नहीं है, तो 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"
```

वैल्यू को बैच में अपडेट करना

JavaScript वर्कलेट के अंदर या बाहर से sharedStorage.batchUpdate() को कॉल किया जा सकता है. साथ ही, तरीकों का क्रम से लगाया गया ऐसा ऐरे पास किया जा सकता है जो चुने गए ऑपरेशनों के बारे में बताता है. हर तरीके का कंस्ट्रक्टर, सेट, जोड़ें, मिटाएं, और हटाएं के लिए, उसी तरह के पैरामीटर स्वीकार करता है जैसे कि उससे जुड़ा अलग-अलग तरीका.

JavaScript से batchUpdate() को कॉल किया जा सकता है या रिस्पॉन्स हेडर का इस्तेमाल किया जा सकता है:

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

batchUpdate() के साथ इस्तेमाल की जा सकने वाली JavaScript के तरीकों में ये शामिल हैं:
- SharedStorageSetMethod(): यह फ़ंक्शन, शेयर किए गए स्टोरेज में की-वैल्यू पेयर लिखता है.
- SharedStorageAppendMethod(): यह शेयर किए गए स्टोरेज में मौजूद किसी कुंजी में वैल्यू जोड़ता है. अगर कुंजी मौजूद नहीं है, तो यह की-वैल्यू पेयर लिखता है.
- SharedStorageDeleteMethod(): यह फ़ंक्शन, Shared Storage से की-वैल्यू पेयर मिटाता है.
- SharedStorageClearMethod(): Shared Storage में मौजूद सभी कुंजियां मिटाता है.
```
sharedStorage.batchUpdate([
new SharedStorageSetMethod('keyOne', 'valueOne'),
new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
new SharedStorageDeleteMethod('keyThree'),
new SharedStorageClearMethod()
]);
```

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

Shared-Storage-Write : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear

रिस्पॉन्स हेडर का इस्तेमाल करने पर, हेडर में मौजूद सभी तरीकों के लिए batchUpdate() होता है.

Shared Storage से डेटा पढ़ना

Shared Storage से डेटा सिर्फ़ वर्कलेट के अंदर से पढ़ा जा सकता है.

await sharedStorage.get('mykey');

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

Shared Storage से मिटाना

JavaScript का इस्तेमाल करके, शेयर किए गए स्टोरेज से डेटा मिटाया जा सकता है. इसके लिए, वर्कलेट के अंदर या बाहर से 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;
```

शेयर किए गए स्टोरेज से, Protected Audience के एक जैसी दिलचस्पी वाले ग्रुप की जानकारी पढ़ने की अनुमति

शेयर किए गए स्टोरेज वर्कलेट से, Protected Audience के एक जैसी दिलचस्पी वाले ग्रुप पढ़े जा सकते हैं. interestGroups() तरीका, StorageInterestGroup ऑब्जेक्ट का कलेक्शन दिखाता है. इसमें AuctionInterestGroup और GenerateBidInterestGroup एट्रिब्यूट शामिल होते हैं.

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

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

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

विकल्प

Shared Storage modifier के सभी तरीके, आखिरी आर्ग्युमेंट के तौर पर विकल्प वाला ऑब्जेक्ट इस्तेमाल करने की सुविधा देते हैं.

withLock

withLock विकल्प का इस्तेमाल करना ज़रूरी नहीं है. अगर यह विकल्प चुना जाता है, तो यह तरीका, Web Locks API का इस्तेमाल करके, तय किए गए संसाधन के लिए लॉक हासिल करने का निर्देश देता है. लॉक का अनुरोध करते समय, लॉक का नाम पास किया जाता है. यह नाम, ऐसे संसाधन को दिखाता है जिसका इस्तेमाल, ऑरिजिन में मौजूद कई टैब, वर्कर या कोड के बीच किया जाता है.

withLock विकल्प का इस्तेमाल, शेयर किए गए स्टोरेज के इन मॉडिफ़ायर तरीकों के साथ किया जा सकता है:

सेट करो
जोड़ें
मिटाएं
मिटाएं
बैच अपडेट

JavaScript या रिस्पॉन्स हेडर का इस्तेमाल करके, लॉक सेट किया जा सकता है:

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

sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });

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

Shared-Storage-Write : set;key="myKey";value="myValue",options;with_lock="myResource"

शेयर किए गए स्टोरेज के लॉक, डेटा के ऑरिजिन के हिसाब से बांटे जाते हैं. ये लॉक, LockManager request() तरीके का इस्तेमाल करके हासिल किए गए किसी भी लॉक से अलग होते हैं. भले ही, वे window या worker कॉन्टेक्स्ट में हों. हालांकि, इनका स्कोप उन लॉक के जैसा ही होता है जो SharedStorageWorklet कॉन्टेक्स्ट में request() का इस्तेमाल करके पाए जाते हैं.

request() तरीके में कॉन्फ़िगरेशन के कई विकल्प मिलते हैं. हालांकि, शेयर किए गए स्टोरेज में हासिल किए गए लॉक हमेशा इन डिफ़ॉल्ट सेटिंग का पालन करते हैं:

mode: "exclusive": एक ही नाम वाले दो लॉक एक साथ नहीं रखे जा सकते.
steal: false: एक ही नाम वाले मौजूदा लॉक को अन्य अनुरोधों के लिए रिलीज़ नहीं किया जाता.
ifAvailable: false: लॉक उपलब्ध होने तक अनुरोधों को अनिश्चित काल के लिए इंतज़ार करना पड़ता है.

`withLock` का इस्तेमाल कब करें

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

लॉक का इस्तेमाल एक और स्थिति में किया जा सकता है. अगर किसी वर्कलेट में एक साथ कई कुंजियां पढ़नी हैं और उनकी स्थिति को सिंक किया जाना चाहिए, तो लॉक का इस्तेमाल किया जा सकता है. ऐसे में, get कॉल को लॉक के साथ रैप करना चाहिए. साथ ही, उन कुंजियों में लिखते समय उसी लॉक को हासिल करना चाहिए.

लॉक का क्रम

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

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

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

एक से ज़्यादा कुंजियों में बदलाव करने का उदाहरण

batchUpdate() के साथ withLock विकल्प का इस्तेमाल करने से, एक ही लॉक को पाने के लिए एक साथ की जा रही अन्य कार्रवाइयों को रोका जा सकता है. batchUpdate() के लिए, पूरे बैच पर सिर्फ़ withLock विकल्प लागू किया जा सकता है. बैच में मौजूद किसी भी अलग-अलग तरीके के ऑब्जेक्ट पर withLock लागू करने से अपवाद दिखता है.

इस उदाहरण में, लॉक का इस्तेमाल किया गया है. इससे यह पक्का किया जाता है कि वर्कलेट में रीड और मिटाने की कार्रवाइयां एक साथ हों. इससे वर्कलेट के बाहर से होने वाले इंटरफ़ेरेंस को रोका जा सकता है.

यहां दिए गए modify-multiple-keys.js उदाहरण में, modify-lock की मदद से keyOne और keyTwo के लिए नई वैल्यू सेट की गई हैं. इसके बाद, वर्कलेट से modify-multiple-keys ऑपरेशन लागू किया गया है:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

इसके बाद, modify-multiple-keys-worklet.js में जाकर, navigator.locks.request() का इस्तेमाल करके लॉक का अनुरोध किया जा सकता है, ताकि ज़रूरत के हिसाब से कुंजियों को पढ़ा और उनमें बदलाव किया जा सके

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

कॉन्टेक्स्ट स्विच करना

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

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

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

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

पहले पक्ष के ऐसे पेज में सेव किया गया डेटा जिसमें तीसरे पक्ष की JavaScript एम्बेड की गई हो. — इस डायग्राम में, पहले पक्ष (ग्राहक) के पेज में सेव किए गए डेटा को दिखाया गया है. इसमें तीसरे पक्ष की JavaScript एम्बेड की गई है.

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

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

विज्ञापन टेक्नोलॉजी या तीसरे पक्ष के कॉन्टेक्स्ट में सेव किया गया डेटा. — इस डायग्राम में, विज्ञापन टेक्नोलॉजी या तीसरे पक्ष के कॉन्टेक्स्ट में सेव किए गए डेटा को दिखाया गया है.

Private Aggregation API

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

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

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

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

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

Shared Storage और Private Aggregation को लागू करना

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

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

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

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

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

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin: *

तीसरे पक्ष के iframe का इस्तेमाल करके, क्रॉस-ऑरिजिन स्क्रिप्ट भी चलाई जा सकती हैं. ऐसे में, Shared Storage की कार्रवाइयां, तीसरे पक्ष के ब्राउज़िंग कॉन्टेक्स्ट में होंगी.

क्रॉस-ऑरिजिन 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);

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

शेयर किए गए स्टोरेज और Private Aggregation की मदद से, क्रॉस-ऑरिजिन 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
    });
  }
}

कस्टम डेटा का ओरिजन

जब dataOrigin को किसी मान्य ऑरिजिन पर सेट किया जाता है, तो dataOrigin के मालिक को, उस dataOrigin के लिए Shared Storage को प्रोसेस करने की सहमति देनी होगी. इसके लिए, उसे /.well-known/shared-storage/trusted-origins पाथ पर worklet स्क्रिप्ट ऑरिजिन की सूची वाली JSON फ़ाइल होस्ट करनी होगी. फ़ाइल में ऑब्जेक्ट की शृंखला होनी चाहिए. साथ ही, उसमें scriptOrigin और contextOrigin कुंजियां होनी चाहिए. इन कुंजियों की वैल्यू, स्ट्रिंग या स्ट्रिंग का अरे हो सकती हैं.

trusted-origins फ़ाइल बनाने के लिए, यहां दी गई जानकारी का इस्तेमाल करें:

कॉल करने वाले व्यक्ति का कॉन्टेक्स्ट
वर्कलेट स्क्रिप्ट का ऑरिजिन और यूआरएल
डेटा का सोर्स और मालिक

यहां दी गई टेबल में बताया गया है कि इस जानकारी के आधार पर, trusted-origins फ़ाइल कैसे बनाई जा सकती है:

कॉल करने वाले व्यक्ति का कॉन्टेक्स्ट	वर्कलेट स्क्रिप्ट का यूआरएल	डेटा का ओरिजिन	डेटा का मालिक	डेटा ओरिजिन के मालिक की भरोसेमंद ओरिजिन वाली JSON फ़ाइल
https://publisher.example	https://publisher.example/script.js	context-origin	https://publisher.example	JSON की ज़रूरत नहीं है
https://publisher.example	https://ad.example/script.js	script-origin	https://ad.example	JSON की ज़रूरत नहीं है
https://publisher.example	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": "https://publisher.example" }]
कोई भी कॉलर	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": "*" }]
https://publisher-a.example, OR https://publisher-b.example	https://cdn-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": "https://cdn-ad.example", "contextOrigin": [ "https://publisher-a.example", "https://publisher-b.example" ] }]
https://publisher.example	https://cdn-a-ad.example/script.js, OR https://cdn-b-ad.example/script.js	https://ad.example	https://ad.example	[{ "scriptOrigin": [ "https://cdn-a-ad.example", "https://cdn-b-ad.example" ], "contextOrigin": "https://publisher.example" }]

उदाहरण के लिए, यहां दिया गया JSON, https://custom-data-origin.example/.well-known/shared-storage/trusted-origins पर होस्ट किया जा सकता है. साथ ही, यह https://custom-data-origin.example ऑरिजिन के लिए, Shared Storage के डेटा को प्रोसेस करने वाले सभी प्रोसेसर को एक साथ इस्तेमाल कर सकता है.

[
  {
    "scriptOrigin": "https://script-origin.a.example",
    "contextOrigin": "https://context-origin.a.example"
  },
  {
    "scriptOrigin": "https://script-origin.b.example",
    "contextOrigin": [
      "https://context-origin.a.example",
      "https://context-origin.b.example"
    ]
}]

अगले चरण

यहां दिए गए पेजों पर, Shared Storage और Private Aggregation API के अहम पहलुओं के बारे में बताया गया है.

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

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

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

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

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