Usage

The Chord web pixel automatically sends the following events to the CDP:

You can customize the web pixel code to add additional custom events or event properties. We recommend keeping track of changes you make to the web pixel code, so you can upgrade in the future.

You may want to add additional events from the Chord tracking plan to your storefront, or add custom events.

1) Publish custom event from theme

First, from your Shopify theme, publish a custom Shopify event with all the data you'll need to construct the Chord tracking event, using Shopify.analytics.publish in a <script> tag. Here's an example:

See more on publishing custom Shopify events here. We recommend prefixing the event name with chord_ or similar to prevent confusion, because all custom Shopify events are sent to all web pixels.

2) Subscribe to custom event from web pixel

Next, you have to update your Chord web pixel code to listen for the new event and sent it to the CDP. Here's an example:

Note that eventName and props are the name and properties of the resulting CDP event, so if you're using an event from the Chord tracking plan, make sure the eventName is correct.

You may need to add some extra configuration for CDP device-mode destinations to work with the Chord web pixel.

The Chord web pixel contains a snippet to loads a CDP library (e.g. Segment's analytics.js). That library in turn loads the JavaScript for any device-mode destinations. For example, the Google Analytics 4 Web Destination loads the gtag.js library client-side and maps Chord events directly to gtag.js events.

Shopify loads web pixel code in an iframe element that has the sandbox attribute defined with the allow-scripts and allow-forms values. This prevents web pixel code from accessing the top frame. Some device-mode destination JavaScript may behave unpredictably in this environment. Shopify's documentation lists the following known limitations of the sandbox environment:

These limitations extend to any device-mode destinations you connect.

The most notable limitation is that window.href returns the sandbox URL instead of the top frame URL. Device-mode destinations that register page views may show a URL that looks like /wpm@bf0a1c21w3867u34522fdp2197aec3mf92342/custom/web-pixel-87687490@19/sandbox/modern/cart instead of the expected storefront URL, if they use window.href instead of the CDP's pageview event properties.

To fix incorrect page view URLs, check the destination settings, and if the destination supports mappings for page views, adjust the destination mapping to map the pageview event property properties.url to the URL property in the destination.

For example, if you're using the Google Analytics 4 Web Destination, navigate to the pre-built "Set Configuration Fields" mapping and map properties.url to the "Page Location", as shown here:

Save the mapping, and the correct URLs will appear in GA4 for future events.

Chord tracking events typically include the customer locale (e.g., "en-US") so you can filter your event data using that property. However, Shopify web pixels don't have access to the current locale, so you need to update the web pixel code to detect it accurately.

If your store only supports one locale, or you don't need to support locale filtering, just update the value of the DEFAULT_LOCALE variable.

If your store supports more than one locale, and you want to filter your event data by locale, you'll need a more customized approach. Shopify web pixels can access cookies and localStorage from the parent frame, so we recommend setting a cookie or a localStorage property with the current locale from your Shopify theme or headless storefront site, and then updating the getMeta function in the Chord web pixel code to read the locale. See Shopify's documentation of the browser API to see how to read cookies or localStorage properties.

For example, if your storefront sets a cookie called locale, you could include that in tracking events like this:

Chord web pixel events use the data provided by Shopify's web pixel framework. There are some ways in which Chord web pixel events differ from Chord events from other libraries, due to the data that's available from Shopify in the web pixel context. Known differences are listed below:

All pre-checkout events

Discounts and coupon data is not available in tracking events until checkout has started. In pre-checkout events like "Cart Viewed", discounts are not factored into the total or value properties, and the coupon property is never populated.

"Cart Viewed"

When a “Buy X get Y” promotion is applied, the line item with the discount is not in the products array, and the value property doesn’t include the value of the discounted line item.

"Product Added"

The event is fired both when a product is initially added to the cart and when the quantity of an existing cart line item is increased.

"Product Removed"

The event is fired both when a line item is completely removed from the cart and when the quantity of an existing cart line item is decreased.

Chord typically sends tracking events to the CDP from two sources:

To associate server events and front-end storefront events with the same session, the website front-end needs to save a few browser identifiers as attributes on the cart or order, so they can be retrieved later by the server source and included in CDP events. This needs to be done from the storefront, before the customer reaches checkout.

If you're using the Chord web pixel to instrument your storefront, you will need to add some code to your Shopify theme to handle this. You need to add two attributes:

In a Shopify theme, you can add cart attributes using the Cart API. We recommend adding these attributes at a time that doesn’t block user interaction with your site, like when the cart page loads or after a product is added to the cart.

See Unifying Data Across Sources for more details.