browser.storage

ब्यौरा

उपयोगकर्ता के डेटा को सेव करने, वापस पाने, और उसमें हुए बदलावों को ट्रैक करने के लिए, chrome.storage API का इस्तेमाल करें.

अनुमतियां

storage

स्टोरेज एपीआई का इस्तेमाल करने के लिए, एक्सटेंशन के मेनिफ़ेस्ट में "storage" अनुमति का एलान करें. उदाहरण के लिए:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

उदाहरण

यहां दिए गए सैंपल, local, sync, और session स्टोरेज एरिया दिखाते हैं:

उदाहरण (स्थानीय)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

उदाहरण (सिंक करना)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

उदाहरण (सेशन)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Storage API के अन्य डेमो देखने के लिए, इनमें से कोई भी सैंपल एक्सप्लोर करें:

कॉन्सेप्ट और इस्तेमाल

Storage API, उपयोगकर्ता के डेटा और स्थिति को बनाए रखने के लिए, एक्सटेंशन के हिसाब से तरीका उपलब्ध कराता है. यह वेब प्लैटफ़ॉर्म के स्टोरेज एपीआई (IndexedDB और स्टोरेज) की तरह ही है. हालांकि, इसे एक्सटेंशन के स्टोरेज की ज़रूरतों को पूरा करने के लिए डिज़ाइन किया गया है. यहां कुछ मुख्य सुविधाओं के बारे में बताया गया है:

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

क्या एक्सटेंशन, वेब स्टोरेज एपीआई का इस्तेमाल कर सकते हैं?

एक्सटेंशन, कुछ मामलों (पॉप-अप और अन्य एचटीएमएल पेजों) में Storage इंटरफ़ेस (window.localStorage से ऐक्सेस किया जा सकता है) का इस्तेमाल कर सकते हैं. हालांकि, हम इन वजहों से इसका सुझाव नहीं देते:

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

सर्विस वर्कर से, वेब स्टोरेज एपीआई से एक्सटेंशन स्टोरेज एपीआई में डेटा ट्रांसफ़र करने के लिए:

  1. ऑफ़स्क्रीन दस्तावेज़ का एचटीएमएल पेज और स्क्रिप्ट फ़ाइल तैयार करें. स्क्रिप्ट फ़ाइल में, कन्वर्ज़न रूटीन और onMessage हैंडलर होना चाहिए.
  2. एक्सटेंशन सर्विस वर्कर में, अपने डेटा के लिए browser.storage देखें.
  3. अगर आपका डेटा नहीं मिलता है, तो createDocument() पर कॉल करें.
  4. वापस किए गए प्रॉमिस के रिज़ॉल्व होने के बाद, कन्वर्ज़न रूटीन शुरू करने के लिए sendMessage() को कॉल करें.
  5. ऑफ़स्क्रीन दस्तावेज़ के onMessage हैंडलर में, कन्वर्ज़न रूटीन को कॉल करें.

एक्सटेंशन में वेब स्टोरेज एपीआई के काम करने के तरीके में भी कुछ बारीकियां हैं. ज़्यादा जानकारी के लिए, स्टोरेज और कुकी लेख पढ़ें.

स्टोरेज और थ्रॉटलिंग की सीमाएं

Storage API के इस्तेमाल से जुड़ी कुछ सीमाएं हैं:

  • डेटा सेव करने से परफ़ॉर्मेंस पर असर पड़ता है. साथ ही, एपीआई में स्टोरेज कोटा शामिल होता है. स्टोरेज को मैनेज करने के लिए, यह तय करें कि आपको कौनसा डेटा सेव करना है.
  • स्टोरेज को खाली होने में समय लग सकता है. अपने कोड को इस तरह से स्ट्रक्चर करें कि वह इस समय को ध्यान में रखे.

स्टोरेज की सीमाओं और उनके पार होने पर क्या होता है, इस बारे में जानकारी के लिए sync, local, और session के कोटे की जानकारी देखें.

स्टोरेज एरिया

Storage API को इन स्टोरेज एरिया में बांटा गया है:

स्थानीय

डेटा को डिवाइस में सेव किया जाता है. साथ ही, एक्सटेंशन हटाने पर डेटा मिटा दिया जाता है. स्टोरेज की सीमा 10 एमबी है. Chrome 113 और इससे पहले के वर्शन में यह सीमा 5 एमबी है. हालांकि, "unlimitedStorage" की अनुमति का अनुरोध करके, इसे बढ़ाया जा सकता है. हमारा सुझाव है कि ज़्यादा डेटा सेव करने के लिए, storage.local का इस्तेमाल करें. डिफ़ॉल्ट रूप से, यह कॉन्टेंट स्क्रिप्ट के लिए उपलब्ध होता है. हालांकि, browser.storage.local.setAccessLevel() को कॉल करके इसे बदला जा सकता है.

मैनेज किया गया

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

डिफ़ॉल्ट रूप से, storage.managed को कॉन्टेंट स्क्रिप्ट के लिए एक्सपोज़ किया जाता है. हालांकि, browser.storage.managed.setAccessLevel() को कॉल करके इस सेटिंग को बदला जा सकता है. नीतियों के बारे में जानकारी पाने के लिए, एडमिन के लिए दस्तावेज़ देखें. managed स्टोरेज एरिया के बारे में ज़्यादा जानने के लिए, स्टोरेज एरिया के लिए मेनिफ़ेस्ट देखें.

सेशन

सेशन स्टोरेज, एक्सटेंशन लोड होने के दौरान डेटा को मेमोरी में सेव रखता है. एक्सटेंशन को बंद करने, फिर से लोड करने, अपडेट करने, और ब्राउज़र को रीस्टार्ट करने पर, स्टोरेज खाली हो जाता है. डिफ़ॉल्ट रूप से, इसे कॉन्टेंट स्क्रिप्ट के लिए उपलब्ध नहीं कराया जाता. हालांकि, browser.storage.session.setAccessLevel() को कॉल करके, इस सेटिंग को बदला जा सकता है. स्टोरेज की सीमा 10 एमबी है. Chrome 111 और इससे पहले के वर्शन में यह सीमा 1 एमबी है.

storage.session इंटरफ़ेस, उन कई इंटरफ़ेस में से एक है जिनका सुझाव हम सर्विस वर्कर के लिए देते हैं.

सिंक करें

अगर उपयोगकर्ता सिंक करने की सुविधा चालू करता है, तो डेटा उन सभी Chrome ब्राउज़र के साथ सिंक हो जाता है जिनमें उपयोगकर्ता ने लॉग इन किया है. अगर इसे बंद किया जाता है, तो यह storage.local की तरह काम करता है. ऑफ़लाइन होने पर, Chrome डेटा को डिवाइस में सेव करता है. ऑनलाइन होने पर, वह डेटा को सिंक करना फिर से शुरू कर देता है. कोटा की सीमा करीब 100 केबी है. इसमें हर आइटम के लिए 8 केबी की सीमा है.

हमारा सुझाव है कि सिंक किए गए ब्राउज़र पर उपयोगकर्ता की सेटिंग को बनाए रखने के लिए, storage.sync का इस्तेमाल करें. अगर आपको उपयोगकर्ता के संवेदनशील डेटा के साथ काम करना है, तो storage.session का इस्तेमाल करें. डिफ़ॉल्ट रूप से, storage.sync को कॉन्टेंट स्क्रिप्ट के लिए एक्सपोज़ किया जाता है. हालांकि, browser.storage.sync.setAccessLevel() को कॉल करके इस सेटिंग को बदला जा सकता है.

तरीके और इवेंट

सभी स्टोरेज एरिया, StorageArea इंटरफ़ेस को लागू करते हैं.

get()

get() तरीके से, StorageArea से एक या उससे ज़्यादा कुंजियां पढ़ी जा सकती हैं.

getBytesInUse()

getBytesInUse() तरीके से, StorageArea के इस्तेमाल किए गए कोटे को देखा जा सकता है.

getKeys()

getKeys() तरीके से, StorageArea में सेव की गई सभी कुंजियां पाई जा सकती हैं.

remove()

remove() तरीके का इस्तेमाल करके, StorageArea से कोई आइटम हटाया जा सकता है.

set()

set() तरीके का इस्तेमाल करके, StorageArea में कोई आइटम सेट किया जा सकता है.

setAccessLevel()

setAccessLevel() तरीके से, StorageArea के ऐक्सेस को कंट्रोल किया जा सकता है.

clear()

clear() तरीके का इस्तेमाल करके, StorageArea से सारा डेटा मिटाया जा सकता है.

onChanged

onChanged इवेंट की मदद से, StorageArea में होने वाले बदलावों पर नज़र रखी जा सकती है.

उपयोग के उदाहरण

यहां दिए गए सेक्शन में, Storage API के इस्तेमाल के सामान्य उदाहरण दिए गए हैं.

स्टोरेज से जुड़े अपडेट का जवाब देना

स्टोरेज में किए गए बदलावों को ट्रैक करने के लिए, इसके onChanged इवेंट में एक लिसनर जोड़ें. स्टोरेज में कुछ भी बदलने पर, वह इवेंट ट्रिगर होता है. सैंपल कोड इन बदलावों को सुनता है:

background.js:

browser.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

इस आइडिया को और बेहतर बनाया जा सकता है. इस उदाहरण में, हमारे पास एक विकल्प पेज है. इसकी मदद से, उपयोगकर्ता "डीबग मोड" को टॉगल कर सकता है. हालांकि, इसे लागू करने का तरीका यहां नहीं दिखाया गया है. विकल्प पेज, नई सेटिंग को तुरंत storage.sync में सेव करता है. साथ ही, सर्विस वर्कर storage.onChanged का इस्तेमाल करके, सेटिंग को जल्द से जल्द लागू करता है.

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
browser.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

स्टोरेज से एसिंक्रोनस प्रीलोड

सर्विस वर्कर हमेशा नहीं चलते हैं. इसलिए, Manifest V3 एक्सटेंशन को कभी-कभी अपने इवेंट हैंडलर को चलाने से पहले, स्टोरेज से डेटा को एसिंक्रोनस तरीके से लोड करना पड़ता है. ऐसा करने के लिए, यहां दिए गए स्निपेट में एसिंक्रोनस action.onClicked इवेंट हैंडलर का इस्तेमाल किया जाता है. यह हैंडलर, अपने लॉजिक को लागू करने से पहले, storageCache ग्लोबल के पॉप्युलेट होने का इंतज़ार करता है.

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  browser.storage.sync.set(storageCache);
});

DevTools

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

टाइप

AccessLevel

Chrome 102+ browser.* Chrome 148 से

स्टोरेज एरिया का ऐक्सेस लेवल.

Enum

"TRUSTED_CONTEXTS"
इससे एक्सटेंशन से मिलने वाले कॉन्टेक्स्ट के बारे में पता चलता है.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
इससे एक्सटेंशन के बाहर से आने वाले कॉन्टेक्स्ट के बारे में पता चलता है.

StorageChange

प्रॉपर्टी

  • newValue

    ज़रूरी नहीं

    अगर आइटम की कोई नई वैल्यू है, तो वह वैल्यू.

  • oldValue

    ज़रूरी नहीं

    अगर आइटम की कोई पुरानी वैल्यू थी, तो वह वैल्यू.

प्रॉपर्टी

local

local स्टोरेज एरिया में मौजूद आइटम, हर मशीन के लिए लोकल होते हैं.

टाइप

StorageArea और ऑब्जेक्ट

प्रॉपर्टी

  • QUOTA_BYTES

    10485760

    लोकल स्टोरेज में ज़्यादा से ज़्यादा कितना डेटा (बाइट में) सेव किया जा सकता है. इसे हर वैल्यू के JSON स्ट्रिंगिफ़िकेशन और हर कुंजी की लंबाई के हिसाब से मेज़र किया जाता है. अगर एक्सटेंशन के पास unlimitedStorage की अनुमति है, तो इस वैल्यू को अनदेखा कर दिया जाएगा. इस सीमा को पार करने वाले अपडेट तुरंत फ़ेल हो जाते हैं. साथ ही, कॉलबैक का इस्तेमाल करने पर runtime.lastError सेट हो जाता है. इसके अलावा, async/await का इस्तेमाल करने पर, Promise को अस्वीकार कर दिया जाता है.

managed

managed स्टोरेज एरिया में मौजूद आइटम, डोमेन एडमिन की कॉन्फ़िगर की गई एंटरप्राइज़ नीति के हिसाब से सेट किए जाते हैं. साथ ही, एक्सटेंशन के लिए ये आइटम रीड-ओनली होते हैं. इस नेमस्पेस में बदलाव करने की कोशिश करने पर गड़बड़ी होती है. किसी नीति को कॉन्फ़िगर करने के बारे में जानने के लिए, स्टोरेज एरिया के लिए मेनिफ़ेस्ट देखें.

टाइप

StorageArea

session

Chrome 102 या इसके बाद का वर्शन Chrome 148 से browser.* MV3 या इसके बाद का वर्शन

session स्टोरेज एरिया में मौजूद आइटम, इन-मेमोरी में सेव किए जाते हैं. इन्हें डिस्क में सेव नहीं किया जाएगा.

टाइप

StorageArea और ऑब्जेक्ट

प्रॉपर्टी

  • QUOTA_BYTES

    10485760

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

sync

sync स्टोरेज एरिया में मौजूद आइटम, Chrome सिंक का इस्तेमाल करके सिंक किए जाते हैं.

टाइप

StorageArea और ऑब्जेक्ट

प्रॉपर्टी

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    अब काम नहीं करता

    storage.sync API में अब डेटा सेव करने के लिए, लगातार राइट ऑपरेशन करने का कोटा नहीं है.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    हर घंटे set, remove या clear से जुड़ी ज़्यादा से ज़्यादा कार्रवाइयां की जा सकती हैं. इसका मतलब है कि हर दो सेकंड में एक बार डेटा लिखा जा सकता है. यह सीमा, कम समय के लिए हर मिनट डेटा लिखने की सीमा से कम है.

    इस सीमा को पार करने वाले अपडेट तुरंत फ़ेल हो जाते हैं. साथ ही, कॉलबैक का इस्तेमाल करने पर या प्रॉमिस अस्वीकार होने पर, runtime.lastError सेट हो जाता है.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    हर मिनट में set, remove या clear से जुड़ी ज़्यादा से ज़्यादा कितनी कार्रवाइयां की जा सकती हैं. यह हर सेकंड दो बार होता है. इससे कम समय में, हर घंटे होने वाले राइट ऑपरेशन की तुलना में ज़्यादा थ्रूपुट मिलता है.

    इस सीमा को पार करने वाले अपडेट तुरंत फ़ेल हो जाते हैं. साथ ही, कॉलबैक का इस्तेमाल करने पर या प्रॉमिस अस्वीकार होने पर, runtime.lastError सेट हो जाता है.

  • QUOTA_BYTES

    102400

    सिंक स्टोरेज में ज़्यादा से ज़्यादा कितना डेटा (बाइट में) सेव किया जा सकता है. इसे हर वैल्यू के JSON स्ट्रिंगिफ़िकेशन और हर कुंजी की लंबाई के हिसाब से मेज़र किया जाता है. इस सीमा को पार करने वाले अपडेट तुरंत फ़ेल हो जाते हैं. साथ ही, कॉलबैक का इस्तेमाल करने पर या प्रॉमिस अस्वीकार होने पर, runtime.lastError सेट हो जाता है.

  • QUOTA_BYTES_PER_ITEM

    8192

    सिंक स्टोरेज में मौजूद हर आइटम का ज़्यादा से ज़्यादा साइज़ (बाइट में). इसे आइटम की वैल्यू की JSON स्ट्रिंग और उसकी कुंजी की लंबाई के हिसाब से मेज़र किया जाता है. इस सीमा से ज़्यादा आइटम वाले अपडेट तुरंत फ़ेल हो जाएंगे. साथ ही, कॉलबैक का इस्तेमाल करने पर या प्रॉमिस अस्वीकार होने पर, runtime.lastError सेट हो जाएगा.

इवेंट

onChanged

browser.storage.onChanged.addListener(
  callback: function,
)

एक या उससे ज़्यादा आइटम बदलने पर ट्रिगर होता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर कुछ ऐसा दिखता है: 

    (changes: object, areaName: string) => void

    • बदलाव

      ऑब्जेक्ट

    • areaName

      स्ट्रिंग