Web pixel extension API
The web pixel extension API gives you access to a select set of controlled APIs for accessing browser APIs and subscribing to customer events, within one of our Lax or Strict sandboxes.
App web pixels
Anchor link to section titled "App web pixels"For app developers integrating app web pixels, pixels are loaded in a strict sandbox. To initialize the web pixel extension API you can import the @shopify/web-pixels-extension package for stronger typing and register your pixel.
For convenience, most of the examples and API references below will assume you’ve deconstructed the API object, like in this example.
Custom web pixels
Anchor link to section titled "Custom web pixels"If you’re integrating a custom pixel using the pixel manager interface in the Shopify admin, then the analytics, browser and the init variables on the api object have already been deconstructed for you and you can call them without having to write any additional boilerplate code.
Web pixel API reference
Anchor link to section titled "Web pixel API reference"The api object has access to the following:
- analytics: Provides access to Shopify's customer event API
- browser: Provides access to specific browser methods that asynchronously execute in the top frame (
sendBeacon,cookie,localStorage,sessionStorage) - init: A JSON object containing a snapshot of the page at time of page render.
- settings: Provides access to the settings JSON object as set by the GraphQL Admin API (Web pixel app extensions only)
analytics.subscribe(event_name, event_callback)
Anchor link to section titled "analytics.subscribe(event_name, event_callback)"Registers a subscription to a stream of customer events of the given name, to be handled by a callback function. In addition to subscribing to individual types of customer events there are also special customer event names that represent a group of customer events, such as all_events, all_standard_events and all_custom_events.
Parameters:
| Name | Type | Description |
|---|---|---|
event_name |
String | String representing the name of a single event or a group of events. |
event_callback(event) |
Function | Callback function for handling events that takes a customer event object containing the event data. |
Special event names:
| Name | Description |
|---|---|
all_events |
Subscribes to all events of all types |
all_standard_events |
Subscribes to only standard events emitted by Shopify |
all_custom_events |
Subscribes to only custom events |
For example, the code below shows the process of subscribing to the page_viewed event.
Examples:
browser.sendBeacon(url, data)
Anchor link to section titled "browser.sendBeacon(url, data)"An asynchronous method for sending data to your pixel endpoint from the top frame. Refer to navigator.sendBeacon for more information.
Parameters:
| Parameter | Type | Description |
|---|---|---|
url |
String | String representing the URL to make the beacon request to |
data |
Object | Object representing the data to encode in the beacon request |
Returns:
Promise of type boolean.
Examples:
browser.cookie.get(name)
Anchor link to section titled "browser.cookie.get(name)"An asynchronous method to get a specific cookie by name from the top frame. Takes a cookie name of type string and returns the cookie value as a string.
Parameters:
| Parameter | Type | Description |
|---|---|---|
name |
String | String representing the name of the cookie |
Returns:
Promise of type string.
Examples:
browser.cookie.set(name, value)
Anchor link to section titled "browser.cookie.set(name, value)"An asynchronous method to set a cookie by name from the top frame. It takes two arguments, a string of form key=value as decribed here or the name of the cookie as the first argument and the value as the second argument.
Parameters:
| Parameter | Type | Description |
|---|---|---|
name |
String | String representing the name of the cookie |
value |
String | String representing the value of the cookie |
Examples:
browser.localStorage.getItem(keyName)
Anchor link to section titled "browser.localStorage.getItem(keyName)"An asynchronous method that, when passed a key name, will return that key's value. Refers to window.localStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to retrieve the value of. |
Returns:
Promise of type string.
Examples:
browser.localStorage.setItem(keyName, keyValue)
Anchor link to section titled "browser.localStorage.setItem(keyName, keyValue)"An asynchronous method that, when passed a key name and value, will add that key to the storage, or update that key's value if it already exists. Refers to window.localStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to retrieve the value of. |
keyValue |
String | A string containing the value you want to give the key you are creating or updating. |
Returns:
Promise of type string.
Examples:
browser.localStorage.removeItem(keyName)
Anchor link to section titled "browser.localStorage.removeItem(keyName)"An asynchronous method that, when passed a key name, will remove that key from the storage. Refers to window.localStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to remove. |
Returns:
Promise of undefined.
Examples:
browser.localStorage.key(index)
Anchor link to section titled "browser.localStorage.key(index)"An asynchronous method that, when passed an integer n, this method will return the name of the nth key in the storage. Refers to window.localStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
index |
Integer | An integer representing the number of the key you want to get the name of. This is a zero-based index. |
Returns:
Promise of type string.
Examples:
browser.localStorage.length()
Anchor link to section titled "browser.localStorage.length()"An asynchronous method that returns an integer representing the number of data items stored in the storage. Refers to window.localStorage in the top frame.
Returns:
Promise of type integer.
Examples:
browser.localStorage.clear()
Anchor link to section titled "browser.localStorage.clear()"An asynchronous method that, when invoked, will empty all keys out of the storage. Refers to window.localStorage in the top frame.
Returns:
Promise of undefined.
Examples:
browser.sessionStorage.getItem(keyName)
Anchor link to section titled "browser.sessionStorage.getItem(keyName)"An asynchronous method that, when passed a key name, will return that key's value. Refers to window.sessionStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to retrieve the value of. |
Returns:
Promise of type string.
Examples:
browser.sessionStorage.setItem(keyName, keyValue)
Anchor link to section titled "browser.sessionStorage.setItem(keyName, keyValue)"An asynchronous method that, when passed a key name and value, will add that key to the storage, or update that key's value if it already exists. Refers to window.sessionStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to retrieve the value of. |
keyValue |
String | A string containing the value you want to give the key you are creating/updating. |
Returns:
Promise of type string.
Examples:
browser.sessionStorage.removeItem(keyName)
Anchor link to section titled "browser.sessionStorage.removeItem(keyName)"An asynchronous method that, when passed a key name, will remove that key from the storage. Refers to window.sessionStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
keyName |
String | A string containing the name of the key you want to remove. |
Returns:
Promise of undefined.
Examples:
browser.sessionStorage.key(index)
Anchor link to section titled "browser.sessionStorage.key(index)"An asynchronous method that, when passed an integer n, this method will return the name of the nth key in the storage. Refers to window.sessionStorage in the top frame.
Parameters:
| Parameter | Type | Description |
|---|---|---|
index |
Integer | An integer representing the number of the key you want to get the name of. This is a zero-based index. |
Returns:
Promise of type string.
Examples:
browser.sessionStorage.length()
Anchor link to section titled "browser.sessionStorage.length()"An asynchronous method that returns an integer representing the number of data items stored in the storage. Refers to window.sessionStorage in the top frame.
Returns:
Promise of type integer.
Examples:
browser.sessionStorage.clear()
Anchor link to section titled "browser.sessionStorage.clear()"An asynchronous method that, when invoked, will empty all keys out of the storage. Refers to window.sessionStorage in the top frame.
Returns:
Promise of undefined.
Examples: