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

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

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

Shared Storage API

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

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

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

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

विज्ञापन टेक्नोलॉजी विशेषज्ञ, JavaScript या रिस्पॉन्स हेडर का इस्तेमाल करके, शेयर किए गए स्टोरेज में डेटा लिख सकते हैं. Shared Storage से डेटा सिर्फ़ एक अलग 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"

वैल्यू को एक साथ अपडेट करना

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

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

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

    batchUpdate() के साथ इस्तेमाल किए जा सकने वाले JavaScript के उपलब्ध तरीकों में ये शामिल हैं:

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

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

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

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

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

await sharedStorage.get('mykey');

जिस ब्राउज़िंग कॉन्टेक्स्ट से वर्कलेट मॉड्यूल लोड किया गया था उसके ऑरिजिन से यह तय होता है कि किसका 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 के इंटरेस्ट ग्रुप की जानकारी पढ़ना

शेयर किए गए स्टोरेज के वर्कलेट से, सुरक्षित ऑडियंस के इंटरेस्ट ग्रुप पढ़े जा सकते हैं. 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);
}

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

विकल्प

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

withLock

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

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

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

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

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

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

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

    Shared-Storage-Write : set;key="myKey";value="myValue";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');
एक से ज़्यादा कुंजियों में बदलाव करने का उदाहरण

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

यहां दिए गए 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 के ऑरिजिन के शेयर किए गए स्टोरेज में सेव करता है.

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

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

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

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

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

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

Private Aggregation API

शेयर किए गए स्टोरेज में सेव किए गए डेटा को मेज़र करने के लिए, Private Aggregation 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 के साथ रिस्पॉन्स देना होगा. ध्यान दें कि क्रॉस-ऑरिजिन अनुरोधों के लिए, सीओआरएस चालू होना चाहिए.

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 पर एपीआई और दस्तावेज़ों के बारे में अपना सुझाव, शिकायत या राय शेयर की जा सकती है.