storage.rst

≡ storage API

• Events
• Types
• Properties

storage API

Use the browser.storage API to store, retrieve, and track changes to user data.

.. rst-class:: api-permission-info

Note

The permission storage is required to use messenger.storage.*.

.. rst-class:: api-main-section

Events

onChanged

.. api-section-annotation-hack::

Fired when one or more items change.

.. api-header::
   :label: Parameters for onChanged.addListener(listener)


   .. api-member::
      :name: ``listener(changes, areaName)``

      A function that will be called when this event occurs.

.. api-header::
   :label: Parameters passed to the listener function


   .. api-member::
      :name: ``changes``
      :type: (object)

      Object mapping each key that changed to its corresponding :ref:`storage.StorageChange` for that item.


   .. api-member::
      :name: ``areaName``
      :type: (string)

      The name of the storage area (:code:`"sync"`, :code:`"local"` or :code:`"managed"`) the changes are for.

.. api-header::
   :label: Required permissions

   - :permission:`storage`

.. rst-class:: api-main-section

Types

StorageArea

.. api-section-annotation-hack::

.. api-header::
   :label: object

   - ``clear([callback])`` Removes all items from storage.
   - ``get([keys], callback)`` Gets one or more items from storage.
   - ``getBytesInUse([keys], callback)`` Gets the amount of space (in bytes) being used by one or more items.
   - ``remove(keys, [callback])`` Removes one or more items from storage.
   - ``set(items, [callback])`` Sets multiple items.

StorageAreaSync

.. api-section-annotation-hack::

.. api-header::
   :label: object

   - ``clear([callback])`` Removes all items from storage.
   - ``get([keys], callback)`` Gets one or more items from storage.
   - ``getBytesInUse([keys], callback)`` Gets the amount of space (in bytes) being used by one or more items.
   - ``remove(keys, [callback])`` Removes one or more items from storage.
   - ``set(items, [callback])`` Sets multiple items.

StorageChange

.. api-section-annotation-hack::

.. api-header::
   :label: object


   .. api-member::
      :name: [``newValue``]
      :type: (any, optional)

      The new value of the item, if there is a new value.


   .. api-member::
      :name: [``oldValue``]
      :type: (any, optional)

      The old value of the item, if there was an old value.

.. rst-class:: api-main-section

Properties

local

.. api-section-annotation-hack::

Items in the local storage area are local to each machine.

managed

.. api-section-annotation-hack::

Items in the managed storage area are set by administrators or native applications, and are read-only for the extension; trying to modify this namespace results in an error.

session

.. api-section-annotation-hack::

Items in the session storage area are kept in memory, and only until the either browser or extension is closed or reloaded.

sync

.. api-section-annotation-hack::

Items in the sync storage area are synced by the browser.