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';

// 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

* }

});

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

// instead of accessing the `api` object, you can deconstruct the properties for convenience

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

console.log(settings);

/**

* {

* "accountID": 234

* }

});

API Object

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
     * }
     */
  });
});

API Object Destructured

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

register(({analytics, browser, settings, init}) => {
  // instead of accessing the `api` object, you can deconstruct the properties for convenience

  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

    console.log(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

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

Was this page helpful?