browser.storage

বিবরণ

ব্যবহারকারীর ডেটা স্টোর, ফিরিয়ে আনা এবং ট্র্যাক করার জন্য chrome.storage API ব্যবহার করুন।

অনুমতি

storage

স্টোরেজ API ব্যবহার করতে, এক্সটেনশন ম্যানিফেস্টে "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 ব্যবহারকারীর ডেটা ও অবস্থা বজায় রাখার জন্য এক্সটেনশন-নির্দিষ্ট উপায় প্রদান করে। এটি ওয়েব প্ল্যাটফর্মের স্টোরেজ API-এর (IndexedDB ও Storage) মতো, তবে এক্সটেনশনের স্টোরেজ সংক্রান্ত প্রয়োজনীয়তা পূরণ করার জন্য ডিজাইন করা হয়েছে। নিচে কয়েকটি গুরুত্বপূর্ণ ফিচার উল্লেখ করা হল:

  • এক্সটেনশন সার্ভিস ওয়ার্কার ও কন্টেন্ট স্ক্রিপ্ট সহ সব এক্সটেনশন কনটেক্সটের Storage API-তে অ্যাক্সেস আছে।
  • JSON সিরিয়ালাইজ করা ভ্যালু অবজেক্ট প্রপার্টি হিসেবে স্টোর করা হয়।
  • Storage API হল বাল্ক রিড ও রাইট অপারেশন সহ অ্যাসিঙ্ক্রোনাস।
  • ব্যবহারকারী ক্যাশে ও ব্রাউজিং ইতিহাস মুছে দিলেও ডেটা থেকে যায়।
  • স্প্লিট ছদ্মবেশী ব্যবহার করার সময়ও সেভ করা সেটিংস বজায় থাকে।
  • এন্টারপ্রাইজ নীতির জন্য এক্সক্লুসিভ শুধু-পড়ার-উপযোগী ম্যানেজ করা স্টোরেজ এরিয়া অন্তর্ভুক্ত করে।

এক্সটেনশন কি ওয়েব স্টোরেজ API ব্যবহার করতে পারে?

এক্সটেনশন কিছু ক্ষেত্রে (পপ-আপ এবং অন্যান্য HTML পৃষ্ঠা) Storage ইন্টারফেস (window.localStorage থেকে অ্যাক্সেসযোগ্য) ব্যবহার করতে পারলেও, আমরা নিম্নলিখিত কারণে এটি ব্যবহার করার সাজেশন দিই না:

  • এক্সটেনশন সার্ভিস ওয়ার্কার Web Storage API ব্যবহার করতে পারে না।
  • কন্টেন্ট স্ক্রিপ্ট, হোস্ট পৃষ্ঠার সাথে স্টোরেজ শেয়ার করে।
  • ব্যবহারকারী তার ব্রাউজিং ইতিহাস মুছে দিলে Web Storage API ব্যবহার করে সেভ করা ডেটা হারিয়ে যায়।

কোনও সার্ভিস ওয়ার্কার থেকে এক্সটেনশন স্টোরেজ API-তে ওয়েব স্টোরেজ API থেকে ডেটা সরাতে:

  1. একটি অফস্ক্রিন ডকুমেন্ট html পৃষ্ঠা এবং স্ক্রিপ্ট ফাইল প্রস্তুত করুন। স্ক্রিপ্ট ফাইলে একটি কনভার্সন রুটিন এবং একটি onMessage হ্যান্ডলার থাকতে হবে।
  2. এক্সটেনশন সার্ভিস ওয়ার্কারে, আপনার ডেটার জন্য browser.storage চেক করুন।
  3. আপনার ডেটা খুঁজে না পেলে, createDocument() নম্বরে কল করুন।
  4. ফেরত আসা প্রমিস রিজলভ হওয়ার পরে, কনভার্সন রুটিন শুরু করতে sendMessage() কল করুন।
  5. অফস্ক্রিন ডকুমেন্টের onMessage হ্যান্ডলারের মধ্যে, কনভার্সন রুটিন কল করুন।

এক্সটেনশনে ওয়েব স্টোরেজ API কীভাবে কাজ করে সেই বিষয়েও কিছু সূক্ষ্ম পার্থক্য আছে। স্টোরেজ ও কুকি নিবন্ধ থেকে আরও জানুন।

স্টোরেজ ও থ্রটলিংয়ের সীমা

Storage API-এর ব্যবহার সংক্রান্ত সীমাবদ্ধতা আছে:

  • ডেটা স্টোর করার জন্য পারফর্ম্যান্সের খরচ হয় এবং API-তে স্টোরেজ কোটা অন্তর্ভুক্ত থাকে। আপনি যে ডেটা স্টোর করতে চান তা প্ল্যান করুন, যাতে আপনি স্টোরেজ স্পেস বজায় রাখতে পারেন।
  • স্টোরেজ সম্পূর্ণ হতে সময় লাগতে পারে। সেই সময়ের জন্য আপনার কোড স্ট্রাকচার করুন।

স্টোরেজ এরিয়া সংক্রান্ত সীমাবদ্ধতা এবং তা অতিক্রম করলে কী হয় সেই সম্পর্কে বিস্তারিত জানতে, sync, local এবং session-এর জন্য কোটা সংক্রান্ত তথ্য দেখুন।

স্টোরেজ এরিয়া

Storage API নিম্নলিখিত স্টোরেজ এরিয়াতে ভাগ করা হয়েছে:

স্থানীয়

ডেটা লোকালি স্টোর করা হয় এবং এক্সটেনশন সরিয়ে দিলে মুছে যায়। স্টোরেজের সীমা হল ১০ এমবি (Chrome 113 ও তার আগের ভার্সনে ৫ এমবি), তবে "unlimitedStorage" অনুমতির জন্য অনুরোধ করে এটি বাড়ানো যেতে পারে। আমরা storage.local ব্যবহার করে আরও বেশি ডেটা স্টোর করার সাজেশন দিই। ডিফল্ট হিসেবে, এটি কন্টেন্ট স্ক্রিপ্টে এক্সপোজ করা থাকে, তবে browser.storage.local.setAccessLevel() কল করে এই আচরণ পরিবর্তন করা যেতে পারে।

ম্যানেজ করা

ম্যানেজ করা স্টোরেজ, নীতি-ইনস্টল করা এক্সটেনশনের জন্য শুধুমাত্র-পড়ার যোগ্য। এটি সিস্টেম অ্যাডমিনিস্ট্রেটর দ্বারা ম্যানেজ করা হয়, ডেভেলপার-নির্ধারিত স্কিমা এবং এন্টারপ্রাইজ নীতি ব্যবহার করে। নীতিগুলি বিকল্পের মতোই, তবে ব্যবহারকারীর পরিবর্তে সিস্টেম অ্যাডমিনিস্ট্রেটর দ্বারা কনফিগার করা হয়। এটি কোনও সংস্থার সব ব্যবহারকারীর জন্য এক্সটেনশনকে আগে থেকে কনফিগার করার অনুমতি দেয়।

ডিফল্ট হিসেবে, storage.managed কন্টেন্ট স্ক্রিপ্টে এক্সপোজ করা হয়, তবে browser.storage.managed.setAccessLevel() কল করে এই আচরণ পরিবর্তন করা যেতে পারে। নীতি সংক্রান্ত তথ্যের জন্য, অ্যাডমিনিস্ট্রেটরদের জন্য ডকুমেন্টেশন দেখুন। managed স্টোরেজ এরিয়া সম্পর্কে আরও জানতে, স্টোরেজ এরিয়ার জন্য ম্যানিফেস্ট দেখুন।

সেশন

এক্সটেনশন লোড হওয়ার সময় সেশন স্টোরেজ মেমরিতে ডেটা ধরে রাখে। এক্সটেনশন বন্ধ, রিলোড, আপডেট করা হলে এবং ব্রাউজার রিস্টার্ট করা হলে স্টোরেজ খালি হয়ে যায়। ডিফল্ট হিসেবে, এটি কন্টেন্ট স্ক্রিপ্টে দেখানো হয় না, তবে browser.storage.session.setAccessLevel() কল করে এই আচরণ পরিবর্তন করা যেতে পারে। স্টোরেজের সীমা হল ১০ এমবি (Chrome 111 এবং তার আগের ভার্সনে ১ এমবি)।

storage.session ইন্টারফেস হল সার্ভিস ওয়ার্কারদের জন্য আমরা সাজেস্ট করি এমন একাধিক ইন্টারফেসের মধ্যে একটি।

সিঙ্ক করুন

ব্যবহারকারী সিঙ্ক করার সুবিধা চালু করলে, ব্যবহারকারী লগ-ইন করে আছেন এমন প্রতিটি Chrome ব্রাউজারের সাথে ডেটা সিঙ্ক হয়। বন্ধ করা থাকলে, এটি storage.local-এর মতো কাজ করে। ব্রাউজার অফলাইন থাকলে Chrome স্থানীয়ভাবে ডেটা স্টোর করে এবং অনলাইন হলে আবার সিঙ্ক করা শুরু করে। কোটার সীমা হল আনুমানিক ১০০ কেবি, আইটেম প্রতি ৮ কেবি।

সিঙ্ক করা ব্রাউজার জুড়ে ব্যবহারকারীর সেটিংস সংরক্ষণ করতে আমরা storage.sync ব্যবহার করার সাজেশন দিই। আপনি সংবেদনশীল ব্যবহারকারীর ডেটা নিয়ে কাজ করলে, পরিবর্তে storage.session ব্যবহার করুন। ডিফল্ট হিসেবে, storage.sync কন্টেন্ট স্ক্রিপ্টে এক্সপোজ করা হয়, তবে browser.storage.sync.setAccessLevel() কল করে এই আচরণ পরিবর্তন করা যেতে পারে।

পদ্ধতি ও ইভেন্ট

সব স্টোরেজ এরিয়া StorageArea ইন্টারফেস প্রয়োগ করে।

get()

get() পদ্ধতি আপনাকে StorageArea থেকে এক বা একাধিক কী পড়তে দেয়।

getBytesInUse()

getBytesInUse() পদ্ধতি আপনাকে StorageArea-এর ব্যবহার করা কোটা দেখতে দেয়।

getKeys()

getKeys() পদ্ধতির মাধ্যমে আপনি StorageArea-এ স্টোর করা সব 'কী' পেতে পারবেন।

remove()

remove() পদ্ধতির সাহায্যে আপনি StorageArea থেকে কোনও আইটেম সরাতে পারবেন।

সেট()

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-এ API ব্যবহার করে আপনি সেভ করা ডেটা দেখতে ও এডিট করতে পারবেন। আরও জানতে, DevTools ডকুমেন্টেশনে এক্সটেনশন স্টোরেজ দেখুন ও এডিট করুন পেজটি দেখুন।

ধরন

AccessLevel

Chrome 102+ ব্রাউজার।* Chrome 148 থেকে

স্টোরেজ এরিয়ার অ্যাক্সেস লেভেল।

Enum

"TRUSTED_CONTEXTS"
এক্সটেনশন থেকে তৈরি হওয়া কনটেক্সট নির্দিষ্ট করে।

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
এক্সটেনশনের বাইরে থেকে আসা প্রসঙ্গ নির্দিষ্ট করে।

StorageChange

প্রপার্টি

  • newValue

    যেকোনও ঐচ্ছিক

    আইটেমের নতুন ভ্যালু, যদি নতুন ভ্যালু থাকে।

  • oldValue

    যেকোনও ঐচ্ছিক

    আইটেমের পুরনো ভ্যালু, যদি কোনও পুরনো ভ্যালু থাকে।

প্রপার্টি

local

local স্টোরেজ এরিয়াতে থাকা আইটেম প্রতিটি মেশিনের জন্য লোকাল।

ধরন

StorageArea ও অবজেক্ট

প্রপার্টি

  • QUOTA_BYTES

    ১০৪৮৫৭৬০

    স্থানীয় স্টোরেজে সর্বাধিক যতটা ডেটা (বাইটে) স্টোর করা যায়, যা প্রতিটি ভ্যালুর JSON স্ট্রিংগিফিকেশন এবং প্রতিটি 'কী'-এর দৈর্ঘ্য যোগ করে পরিমাপ করা হয়। এক্সটেনশনের unlimitedStorage অনুমতি থাকলে এই ভ্যালু উপেক্ষা করা হবে। এই সীমা অতিক্রম করার কারণ হতে পারে এমন আপডেট অবিলম্বে ব্যর্থ হয় এবং কলব্যাক ব্যবহার করার সময় runtime.lastError সেট করে অথবা async/await ব্যবহার করলে একটি প্রত্যাখ্যাত প্রমিস সেট করে।

managed

managed স্টোরেজ এরিয়ার আইটেমগুলি ডোমেন অ্যাডমিনিস্ট্রেটরের কনফিগার করা এন্টারপ্রাইজ নীতি দ্বারা সেট করা হয় এবং এক্সটেনশনের জন্য শুধুমাত্র পড়ার যোগ্য; এই নেমস্পেস পরিবর্তন করার চেষ্টা করলে সমস্যা হয়। কোনও নীতি কনফিগার করার ব্যাপারে তথ্যের জন্য, স্টোরেজ এরিয়ার জন্য ম্যানিফেস্ট দেখুন।

ধরন

StorageArea

session

Chrome 102+ ব্রাউজার।* Chrome 148 থেকে MV3+

session স্টোরেজ এরিয়ার আইটেম ইন-মেমরিতে স্টোর করা হয় এবং ডিস্কে সেভ করা হবে না।

ধরন

StorageArea ও অবজেক্ট

প্রপার্টি

  • QUOTA_BYTES

    ১০৪৮৫৭৬০

    মেমরিতে স্টোর করা যেতে পারে এমন ডেটার সর্বাধিক পরিমাণ (বাইটে), যা প্রতিটি ভ্যালু এবং কী-এর ডায়নামিক্যালি বরাদ্দ করা মেমরির ব্যবহার অনুমান করে পরিমাপ করা হয়। এই সীমা অতিক্রম করার কারণে আপডেটগুলি অবিলম্বে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস প্রত্যাখ্যান করা হলে runtime.lastError সেট করবে।

sync

sync স্টোরেজ এরিয়ার আইটেম Chrome Sync ব্যবহার করে সিঙ্ক করা হয়।

ধরন

StorageArea ও অবজেক্ট

প্রপার্টি

  • MAX_ITEMS

    ৫১২

    সিঙ্ক স্টোরেজে সর্বাধিক যতগুলি আইটেম স্টোর করা যাবে। এই সীমা অতিক্রম করার কারণ হতে পারে এমন আপডেট অবিলম্বে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস প্রত্যাখ্যান করা হলে runtime.lastError সেট করবে।

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    ১০০০০০০

    বন্ধ করে দেওয়া হয়েছে

    storage.sync API-তে আর কোনও সাসটেইনড রাইট অপারেশন কোটা নেই।

  • MAX_WRITE_OPERATIONS_PER_HOUR

    ১৮০০

    প্রতি ঘণ্টায় সর্বাধিক যতগুলি set, remove বা clear অপারেশন করা যেতে পারে। এটি প্রতি ২ সেকেন্ডে ১টি, যা স্বল্প মেয়াদে প্রতি মিনিটে বেশি লেখার সীমার চেয়ে কম।

    এই সীমা অতিক্রম করার কারণে আপডেটগুলি অবিলম্বে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস প্রত্যাখ্যান করা হলে runtime.lastError সেট করবে।

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    ১২০

    প্রতি মিনিটে সর্বাধিক যতগুলি set, remove বা clear অপারেশন করা যেতে পারে। এটি প্রতি সেকেন্ডে ২, যা অল্প সময়ের মধ্যে প্রতি-ঘণ্টা-লেখার চেয়ে বেশি থ্রুপুট প্রদান করে।

    এই সীমা অতিক্রম করার কারণে আপডেটগুলি অবিলম্বে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস প্রত্যাখ্যান করা হলে runtime.lastError সেট করবে।

  • QUOTA_BYTES

    ১০২৪০০

    সিঙ্ক স্টোরেজে স্টোর করা যেতে পারে এমন ডেটার সর্বাধিক মোট পরিমাণ (বাইটে), প্রতিটি ভ্যালুর JSON স্ট্রিংগিফিকেশন এবং প্রতিটি 'কী'-এর দৈর্ঘ্য দ্বারা পরিমাপ করা হয়। এই সীমা অতিক্রম করার কারণে আপডেটগুলি অবিলম্বে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস প্রত্যাখ্যান করা হলে runtime.lastError সেট করবে।

  • QUOTA_BYTES_PER_ITEM

    ৮১৯২

    সিঙ্ক স্টোরেজে প্রতিটি আইটেমের সর্বাধিক সাইজ (বাইটে), যা এর ভ্যালুর JSON স্ট্রিংগিফিকেশন এবং এর কী-এর দৈর্ঘ্য দ্বারা পরিমাপ করা হয়। এই সীমার চেয়ে বড় আইটেম আছে এমন আপডেট সাথে সাথে ব্যর্থ হবে এবং কলব্যাক ব্যবহার করার সময় বা কোনও প্রমিস বাতিল করা হলে runtime.lastError সেট করবে।

ইভেন্ট

onChanged

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

এক বা একাধিক আইটেম পরিবর্তন হলে ফায়ার করা হয়।

প্যারামিটারগুলি

  • কলব্যাক

    ফাংশন

    callback প্যারামিটারটি দেখতে এইরকম: 

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

    • বদল

      অবজেক্ট

    • areaName

      স্ট্রিং