---
title: browser
description: >-
  Provides access to specific browser methods that asynchronously execute in the
  top frame (`cookie`, `localStorage`, `sessionStorage`)
api_name: web-pixels
source_url:
  html: 'https://shopify.dev/docs/api/web-pixels-api/standard-api/browser'
  md: 'https://shopify.dev/docs/api/web-pixels-api/standard-api/browser.md'
---

# browserinterface

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

## Properties

* cookie

  BrowserCookie

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

* localStorage

  BrowserLocalStorage

* sessionStorage

  BrowserSessionStorage

* sendBeacon

  (url: string, body?: string) => Promise\<boolean>

  deprecated

  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\`

  ```ts
  (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.

  ```ts
  (cookieOrName: string, value?: string) => Promise<string>
  ```

```ts
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.

  ```ts
  () => Promise<void>
  ```

* getItem

  When passed a key name, will return that key's value.

  ```ts
  (key: string) => Promise<string>
  ```

* key

  When passed a number n, this method will return the name of the nth key in the storage.

  ```ts
  (index: number) => Promise<string>
  ```

* length

  Returns an integer representing the number of data items stored in the Storage object.

  ```ts
  () => Promise<number>
  ```

* removeItem

  When passed a key name, will remove that key from the storage.

  ```ts
  (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.

  ```ts
  (key: string, value: any) => Promise<void>
  ```

```ts
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.

  ```ts
  () => Promise<void>
  ```

* getItem

  When passed a key name, will return that key's value.

  ```ts
  (key: string) => Promise<string>
  ```

* key

  When passed a number n, this method will return the name of the nth key in the storage.

  ```ts
  (index: number) => Promise<string>
  ```

* length

  Returns an integer representing the number of data items stored in the Storage object.

  ```ts
  () => Promise<number>
  ```

* removeItem

  When passed a key name, will remove that key from the storage.

  ```ts
  (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.

  ```ts
  (key: string, value: any) => Promise<void>
  ```

```ts
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

  ```javascript
  /**
   * 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

  ```javascript
  /**
   * 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

  ```javascript
  /**
   * 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();
  ```