browser

Provides access to specific browser methods that asynchronously execute in the top frame (cookie, localStorage, sessionStorage)

Anchor to propertiesProperties

Anchor to cookie cookie: This object replaces the native document.cookie API and provides a setter/getter to set cookies on the top frame.
Anchor to localStorage localStorage
Anchor to sessionStorage sessionStorage
Anchor to sendBeacon sendBeacon (url: string, body?: string) => Promise<boolean>: Deprecated
The navigator.sendBeacon() method asynchronously sends an HTTP POST request containing a small amount of data to a web server. Please use the standard web fetch api with the option keepalive: true to achieve this functionality.

BrowserCookie

This object replaces the native document.cookie API and provides a setter/getter to set cookies on the top frame.

get
An asynchronous method to get a specific cookie by name. Takes a cookie name of type `string` and returns the cookie value as a `string`
```
(name?: string) => Promise<string>
```
set
An asynchronous method to set a cookie by name. It takes two arguments, a string of form `key=value` as [described here](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie#write_a_new_cookie) or the name of the cookie as the first argument and the value as the second argument.
```
(cookieOrName: string, value?: string) => Promise<string>
```

export interface BrowserCookie {
  /**
   * An asynchronous method to get a specific cookie by name. Takes a cookie
   * name of type `string` and returns the cookie value as a `string`
   */
  get?: (name?: string) => Promise<string>;

  /**
   * An asynchronous method to set a cookie by name. It takes two arguments, a string of form `key=value` as [described here](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie#write_a_new_cookie) or the name of the cookie as the first argument and the value as the second argument.
   */
  set?: (cookieOrName: string, value?: string) => Promise<string>;
}

BrowserLocalStorage

clear
When invoked, will empty all keys out of the storage.
```
() => Promise<void>
```
getItem
When passed a key name, will return that key's value.
```
(key: string) => Promise<string>
```
key
When passed a number n, this method will return the name of the nth key in the storage.
```
(index: number) => Promise<string>
```
length
Returns an integer representing the number of data items stored in the Storage object.
```
() => Promise<number>
```
removeItem
When passed a key name, will remove that key from the storage.
```
(key: string) => Promise<void>
```
setItem
When passed a key name and value, will add that key to the storage, or update that key's value if it already exists.
```
(key: string, value: any) => Promise<void>
```

export interface BrowserLocalStorage {
  /**
   * When invoked, will empty all keys out of the storage.
   */
  clear?: () => Promise<ReturnType<WindowLocalStorage['localStorage']['clear']>>;

  /**
   * When passed a key name, will return that key's value.
   */
  getItem?: (
    key: string,
  ) => Promise<ReturnType<WindowLocalStorage['localStorage']['getItem']>>;

  /**
   * When passed a number n, this method will return the name of the nth key in
   * the storage.
   */
  key?: (
    index: number,
  ) => Promise<ReturnType<WindowLocalStorage['localStorage']['key']>>;

  /**
   * Returns an integer representing the number of data items stored in the
   * Storage object.
   */
  length?: () => Promise<WindowLocalStorage['localStorage']['length']>;

  /**
   * When passed a key name, will remove that key from the storage.
   */
  removeItem?: (
    key: string,
  ) => Promise<ReturnType<WindowLocalStorage['localStorage']['removeItem']>>;

  /**
   * When passed a key name and value, will add that key to the storage, or
   * update that key's value if it already exists.
   */
  setItem?: (
    key: string,
    value: any,
  ) => Promise<ReturnType<WindowLocalStorage['localStorage']['setItem']>>;
}

BrowserSessionStorage

clear
When invoked, will empty all keys out of the storage.
```
() => Promise<void>
```
getItem
When passed a key name, will return that key's value.
```
(key: string) => Promise<string>
```
key
When passed a number n, this method will return the name of the nth key in the storage.
```
(index: number) => Promise<string>
```
length
Returns an integer representing the number of data items stored in the Storage object.
```
() => Promise<number>
```
removeItem
When passed a key name, will remove that key from the storage.
```
(key: string) => Promise<void>
```
setItem
When passed a key name and value, will add that key to the storage, or update that key's value if it already exists.
```
(key: string, value: any) => Promise<void>
```

export interface BrowserSessionStorage {
  /**
   * When invoked, will empty all keys out of the storage.
   */
  clear?: () => Promise<
    ReturnType<WindowSessionStorage['sessionStorage']['clear']>
  >;

  /**
   * When passed a key name, will return that key's value.
   */
  getItem?: (
    key: string,
  ) => Promise<ReturnType<WindowSessionStorage['sessionStorage']['getItem']>>;

  /**
   * When passed a number n, this method will return the name of the nth key in
   * the storage.
   */
  key?: (
    index: number,
  ) => Promise<ReturnType<WindowSessionStorage['sessionStorage']['key']>>;

  /**
   * Returns an integer representing the number of data items stored in the
   * Storage object.
   */
  length?: () => Promise<WindowSessionStorage['sessionStorage']['length']>;

  /**
   * When passed a key name, will remove that key from the storage.
   */
  removeItem?: (
    key: string,
  ) => Promise<
    ReturnType<WindowSessionStorage['sessionStorage']['removeItem']>
  >;

  /**
   * When passed a key name and value, will add that key to the storage, or
   * update that key's value if it already exists.
   */
  setItem?: (
    key: string,
    value: any,
  ) => Promise<ReturnType<WindowSessionStorage['sessionStorage']['setItem']>>;
}

Examples

Accessing Standard Api

Cookie

/**
 * browser.cookie.get(name)
 *
 * @param {name} - String representing the name of the cookie
 * @return {Promise} - Promise of type string
 */

const user_id = await browser.cookie.get('my_user_id');

/**
 * browser.cookie.set(name)
 *
 * @param {name} - String representing the name of the cookie
 * @param {value} - String representing the value of the cookie
 * @return {Promise} - Promise of type string
 */

browser.cookie.set('my_user_id', 'ABCX123');
browser.cookie.set('my_user_id=ABCX123; expires=Thu, 18 Dec 2013 12:00:00');

LocalStorage

/**
 * browser.localStorage.getItem(url, data)
 *
 * @param {keyName} - String containing the name of the key you want to retrieve the value of.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.getItem('foo');

/**
 * browser.localStorage.setItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @param {keyValue} - A string containing the value you want to give the key you are creating or updating.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.setItem('foo', 'bar');

/**
 * browser.localStorage.removeItem(keyName)
 *
 * @param {keyName} - A string containing the name of the key you want to remove.
 * @return {Promise} - Promise of undefined.
 */
browser.localStorage.removeItem('foo');

/**
 * browser.localStorage.key(index)
 *
 * @param {index} - An integer representing the number of the key you want to get the name of. This is a zero-based index.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.key(2);

/**
 * browser.localStorage.length()
 *
 * @return {Promise} - Promise of type integer.
 */
browser.localStorage.length();

/**
 * browser.localStorage.clear()
 *
 * @return {Promise} - Promise of undefined.
 */
browser.localStorage.clear();

SessionStorage

/**
 * browser.sessionStorage.getItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.getItem('foo');

/**
 * browser.sessionStorage.setItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @param {keyValue} - A string containing the value you want to give the key you are creating or updating.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.setItem('foo', 'bar');

/**
 * browser.sessionStorage.removeItem(keyName)
 *
 * @param {keyName} - A string containing the name of the key you want to remove.
 * @return {Promise} - Promise of undefined.
 */
browser.sessionStorage.removeItem('foo');

/**
 * browser.sessionStorage.key(index)
 *
 * @param {index} - An integer representing the number of the key you want to get the name of. This is a zero-based index.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.key(2);

/**
 * browser.sessionStorage.length()
 *
 * @return {Promise} - Promise of type integer.
 */
browser.sessionStorage.length();

/**
 * browser.sessionStorage.clear()
 *
 * @return {Promise} - Promise of undefined.
 */
browser.sessionStorage.clear();

Was this page helpful?