Skip to main content

Web Pixels API

The Web Pixels API gives you access to a set of controlled APIs for accessing browser APIs and subscribing to customer events, within one of our Lax or Strict sandboxes.

Anchor to app-web-pixelsApp 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. Once initialized, the api object (the Standard API) has access to the following properties:

  • analytics: Provides access to Shopify's customer event API
  • browser: Provides access to specific browser methods that asynchronously execute in the top frame (cookie, localStorage, sessionStorage)
  • init: A JSON object containing a snapshot of the page at time of page render.
    • Contains a context field that provides the Context of the page at the time of page render
    • Contains a data field that provides access to the Cart and Customer objects at the time of page render
  • settings: Provides access to the settings JSON object as set by the GraphQL Admin API (Web pixel app extensions only)

To learn more about these Standard API properties, or how to create app pixels, please view the following documentation.

API ReferenceStandard API
API ReferenceApp Pixel Tutorial
API ReferenceApp Pixel FAQ

Initializing the API

import {register} from '@shopify/web-pixels-extension';

register((api) => {
// you can access the web pixel extension API in here
api.analytics.subscribe('page_viewed', (event) => {
console.log(`Event Name is: ${event.name}`);
// Event Name is: page_viewed

// Set a cookie with the standard API
api.browser.cookie.set('my_user_id', 'ABCX123');

console.log(`Customer Name: ${api.init.data.customer.firstName}`);
// Customer Name: Bogus

console.log(api.settings);
/**
* {
* "accountID": 234
* }
*/
});
});

Anchor to custom-web-pixelsCustom Web Pixels

Custom Pixels are loaded within a lax sandbox and configured within the pixel manager interface in the Shopify admin. For this developer interface, 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.

Unavailable Settings Property

Unlike with App Pixels, custom pixels do not have access to the settings property

API ReferenceStandard API
API ReferenceCustom Pixel Tutorial

Initializing the API

API Object

// With Custom Pixels, you can simply write the following without the "register" boilerplate.

analytics.subscribe('page_viewed', (event) => {
console.log(`Event Name is: ${event.name}`);
// Event Name is: page_viewed

// Set a cookie with the standard API
browser.cookie.set('my_user_id', 'ABCX123');

console.log(`Customer Name: ${init.data.customer.firstName}`);
// Customer Name: Bogus
});

Anchor to customer-events-referenceCustomer Events Reference

After setting up your App Pixel or Custom Pixel, you can use these pixels to subscribe to additional customer events. We publish and maintain a list of commonly used standard events such as page_viewed, product_viewed and checkout progression events.

If you would like additional events not covered by our list, you can create, publish and subscribe to your own custom events.

To subscribe to multiple events at once you can use: all_events, all_standard_events, all_custom_events, all_dom_events. Please take note that the contents of these event subscriptions are subject to change as events are added or modified. Please view the following documentation for more details about customer events:

API ReferenceStandard Events
API ReferenceCustom Events
API ReferenceDOM Events
API ReferenceAdvanced DOM Events
API ReferencePixel Privacy