Usage
The Chord web pixel automatically sends the following events to Segment:
- A page event for every page view
- An identify event when a customer submits contact information during checkout, or logs into their account
- The following track events:
- "Cart Viewed"
- "Checkout Started"
- "Checkout Step Completed"
- "Order Completed"
- "Payment Info Entered"
- "Product List Viewed"
- "Product Added"
- "Product Removed"
- "Product Viewed"
- "Products Searched"
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 Segment. Here's an example:
Note that eventName and props are the name and properties of the resulting Segment 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 Segment device-mode destinations to work with the Chord web pixel.
The Chord web pixel loads Segment's analytics.js library. The analytics.js library in turn loads the JavaScript for any Segment 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 Segment device-mode destination JavaScript may behave unpredictably in this environment. Shopify's documentation lists the following known limitations of the sandbox environment:
- Can't render user interface elements, such as buttons, forms, banners, or modals
- Automatic detection of events from DOM scraping
- Automatic detection of metadata from DOM scraping
- Automatic detection of user information, such as email and phone, from DOM scraping
- Automatic detection of outbound link clicks from DOM scraping
- Automatic detection of page scrolling
- Automatic detection of clicks and mouse movement to create heatmaps from DOM scraping
These limitations extend to any Segment device-mode destinations you connect.
The most notable limitation is that window.href returns the sandbox URL instead of the top frame URL. Segment 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 Segment's pageview event properties.
To fix incorrect page view URLs, check the Segment destination settings, and if the destination supports mappings for page views, adjust the destination mapping to map the Segment 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:
![Document image Document image](https://images.archbee.com/TmutqdeXiIw-V3gBZXVjd/u7Ah2smOfh73TOgmBCB5G_image.png?format=webp)
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:
- Your website front-end, either using the Chord Shopify web pixel, theme snippet, or @chordcommerce/analytics, and;
- Chord's server events service, which sends tracking events from a Shopify custom source function in your Segment workspace in response to webhook triggers from Shopify.
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 Segment 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:
Attribute name | Description | Example value |
_cdpAnonymousId | Segment session identifier. Read this from the ajs_anonymous_id cookie. | 32e5434e-ed1a-42bf-acd9-64de286879fa |
_googleClientId | Google client ID. Read this from the _ga cookie, with .substring(6). | 961446296.1716300180 |
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.