This guide describes how web pixels work, introduces the sandbox environments that are available, and provides some considerations before you get started.
How web pixels workAnchor link to section titled "How web pixels work"
After you’ve created your web pixel and configured it to a merchant’s shop, your pixel is able to load in the shop’s online store. As a customer browses the online store, they’ll trigger customer events that are published to a Shopify data layer or event bus. Your pixel can subscribe to the events on this data layer and then transform the event payloads into a format that conforms to the requirements of your pixel’s data collection endpoint.
Web pixel app extensions provide partners with a simplified process for managing and processing behavioral data, by loading pixels in a secure sandbox environment with APIs for subscribing to customer events. Web pixel app extensions provide the following benefits to merchants and partners:
- Eliminate or minimize the need for merchants to add tracking code
- Securely access all surfaces, like storefront, checkout and post-purchase pages
- Control what data partners have access to
- Avoid performance and privacy alerts
- Provide a smaller pixel code libraries with the removal of excess DOM manipulation code
Requesting consentAnchor link to section titled "Requesting consent"
Web pixel app extensions are compatible with the Customer Privacy API, so you can request consent as needed. Web pixel app extension callbacks are executed only after the visitor has given consent. When the buyer gives consent, all registered events are replayed to capture any events that already occurred on the page.
Sandbox environmentsAnchor link to section titled "Sandbox environments"
Web pixels are loaded in a sandbox on a visitor's browser, and are designed to give merchants and buyers complete control over what data is accessible to Partners. These controls mean some common features of pixels won’t work the same or won’t work at all. Specifically, these include any features that rely on scraping the DOM for information or attempting to write to the DOM. Although these limitations may seem constraining, most can be overcome by leveraging the data passed into the sandbox using the web pixel extension API.
While this documentation is focused on web pixel app extensions, it's important to note that there are two types of sandbox environments:
Strict sandbox (Web pixel app extension)Anchor link to section titled "Strict sandbox (Web pixel app extension)"
App developers create web pixel app extensions which are loaded in a
self, a reference back to the global object.
console, which is the same
consoleavailable in the browser and can be used for printing to the browser’s console. Note: Your app should not log any content when running in production.
clearInterval, which behave the same as they do outside a web worker
fetchand related globals (
Response), which can be used to make HTTP requests to arbitrary endpoints. Note: Any requests you make must explicitly support cross-origin resource sharing (CORS), just as they would if the request were coming from
fetch()outside of a web worker.
window.document won't work in this environment. You can use contextual APIs available to web pixel app extensions to replicate specific browser API functionality.
Lax sandbox (Custom web pixel)Anchor link to section titled "Lax sandbox (Custom web pixel)"
Custom pixels are loaded in a
lax sandbox environment. The lax sandbox is an
iframe element that has the
sandbox attribute defined with the
lax sandbox cannot access the top frame. There are certain properties that return different values because you cannot access the top frame. For example,
window.href returns the sandbox URL instead of the top frame URL.
This feature is intended for merchants to use and more information can be found in the help docs. We strongly recommend partners create apps and encourage merchants to use their apps instead of creating Custom Pixels, for greater integration.
- Create a web pixel app extension to subscribe to all events emitted by Shopify.