chrome.storage

ब्यौरा

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

अनुमतियां

storage

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

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

उदाहरण

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

लोकल

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

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

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

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

सेशन

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

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

सिंक करें

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

हमारा सुझाव है कि सिंक किए गए ब्राउज़र पर उपयोगकर्ता की सेटिंग बनाए रखने के लिए, storage.sync का इस्तेमाल करें. अगर आपको उपयोगकर्ता के संवेदनशील डेटा के साथ काम करना है, तो इसके बजाय storage.session का इस्तेमाल करें. डिफ़ॉल्ट रूप से, storage.sync को कॉन्टेंट स्क्रिप्ट के लिए उपलब्ध कराया जाता है. हालांकि, chrome.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:

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);
});

DevTools

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

टाइप

AccessLevel

Chrome 102 या इसके बाद का वर्शन

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

Enum

"TRUSTED_CONTEXTS"
यह एक्सटेंशन से जनरेट हुए कॉन्टेक्स्ट के बारे में बताता है.

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

StorageChange

प्रॉपर्टी

  • newValue

    कोई भी ज़रूरी नहीं है

    अगर आइटम की कोई नई वैल्यू है, तो वह यहां दिखेगी.

  • oldValue

    कोई भी ज़रूरी नहीं है

    अगर आइटम की कोई पुरानी वैल्यू मौजूद थी, तो वह यहां दिखेगी.

प्रॉपर्टी

local

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

टाइप

StorageArea & object

प्रॉपर्टी

  • QUOTA_BYTES

    10485760

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

managed

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

टाइप

StorageArea

session

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

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

टाइप

StorageArea & object

प्रॉपर्टी

  • QUOTA_BYTES

    10485760

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

sync

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

टाइप

StorageArea & object

प्रॉपर्टी

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    अब सेवा में नहीं है

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

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

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

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

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

इवेंट

onChanged

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

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

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

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

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

    • बदलाव

      ऑब्जेक्ट

    • areaName

      स्ट्रिंग