chrome.storage

ब्यौरा

अनुमतियां

खास जानकारी

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

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

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

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

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

1. कन्वर्ज़न रूटीन और [onMessage][on-message] हैंडलर की मदद से, स्क्रीन से बाहर का दस्तावेज़ बनाएं.
2. स्क्रीन पर न दिखने वाले दस्तावेज़ में कन्वर्ज़न रूटीन जोड़ें.
3. एक्सटेंशन के सर्विस वर्कर में, अपने डेटा के लिए chrome.storage की जांच करें.
4. अगर आपका डेटा नहीं मिलता है, तो [create][create-offscreen] एक ऑफ़स्क्रीन दस्तावेज़ बनाएं और कन्वर्ज़न रूटीन शुरू करने के लिए [sendMessage()][send-message] को कॉल करें.
5. स्क्रीन से बाहर मौजूद दस्तावेज़ के onMessage हैंडलर में, कन्वर्ज़न रूटीन को कॉल करें.

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

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

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

storage.local

डेटा को स्थानीय तौर पर सेव किया जाता है. एक्सटेंशन हटाने पर, यह डेटा मिट जाता है. कोटा की सीमा करीब 10 एमबी है. हालांकि, "unlimitedStorage" की अनुमति का अनुरोध करके इसे बढ़ाया जा सकता है. ज़्यादा डेटा सेव करने के लिए, इसका इस्तेमाल करें.

storage.sync

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

storage.session

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

storage.managed

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

मेनिफ़ेस्ट

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

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

इस्तेमाल

यहां local, sync, और session स्टोरेज एरिया के उदाहरण दिए गए हैं:

storage.local

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.sync

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.session

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

managed स्टोरेज एरिया के बारे में ज़्यादा जानने के लिए, स्टोरेज एरिया के लिए मेनिफ़ेस्ट देखें.

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

Storage API में डेटा जोड़ने का मतलब यह नहीं है कि डेटा को किसी बड़े ट्रक में रखा जा रहा है. स्टोरेज में डेटा जोड़ने को पाइप में कुछ डालने जैसा समझें. पाइप में पहले से ही कुछ मटीरियल मौजूद हो सकता है और यह पूरी तरह से भरा भी हो सकता है. स्टोरेज में डेटा जोड़ने और उसके रिकॉर्ड होने के बीच हमेशा कुछ समय लगता है.

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

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

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

स्टोरेज के अपडेट के लिए सिंक्रोनस जवाब

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

background.js:

chrome.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;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.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
chrome.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);
  }
});

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

सर्विस वर्कर हमेशा चालू नहीं रहते हैं. इसलिए, मेनिफ़ेस्ट V3 एक्सटेंशन को कभी-कभी अपने इवेंट हैंडलर को एक्ज़ीक्यूट करने से पहले, स्टोरेज से डेटा को एसिंक्रोनस तरीके से लोड करना पड़ता है. इसके लिए, यहां दिए गए स्निपेट में एसिंक action.onClicked इवेंट हैंडलर का इस्तेमाल किया गया है. यह 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 = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.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;
  chrome.storage.sync.set(storageCache);
});

एक्सटेंशन के उदाहरण

Storage API के अन्य डेमो देखने के लिए, इनमें से कोई उदाहरण देखें:

• ग्लोबल सर्च एक्सटेंशन.
• पानी के अलार्म का एक्सटेंशन.

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