---
title: Usage
slug: usage
createdAt: 2024-05-15T18:59:56.884Z
---

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

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

## Adding custom events

You may want to add custom events from the [Chord tracking plan](https://docs.chord.co/tracking-plan) to your storefront to track any other events users perform on your store. These custom events will be added to the Chord data warehouse.

:::hint{type="warning"}
Other CDP destinations (e.g. third party services) do not support sending custom events - they will only respond to events within Chord's tracking plan.
:::

**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:

```javascript
const event_name = 'chord_navigation_clicked';
const event_data = {
  category: 'Support',
  label: 'Contact Us',
  navigation_placement: 'footer',
  navigation_title: 'Contact',
  navigation_url: 'https://example.com/contact',
}

Shopify.analytics.publish(event_name, event_data);
```

See more on publishing custom Shopify events [here](https://shopify.dev/docs/api/web-pixels-api/emitting-data#publishing-custom-events). 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:

```javascript
analytics.subscribe('chord_navigation_clicked', async (event) => {
  const eventName = 'Navigation Clicked' // CDP event name
  const props = event.customData // CDP event properties
  
  await track(eventName, props)
})
```

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](https://docs.chord.co/tracking-plan), make sure the `eventName` is correct.

## Using with CDP device-mode destinations

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 load a CDP library (e.g. Chord CDP or Segment's [analytics.js](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/)). That library in turn loads the JavaScript for any [device-mode destinations](https://segment.com/docs/connections/destinations/). For example, the [Google Analytics 4 Web Destination](https://segment.com/docs/connections/destinations/catalog/actions-google-analytics-4-web/#faq-and-troubleshooting) loads the gtag.js library client-side and maps Chord events directly to gtag.js events.&#x20;

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](https://help.shopify.com/en/manual/promoting-marketing/pixels/overview#pixels-sandbox-limitations) 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 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](https://segment.com/docs/connections/destinations/catalog/actions-google-analytics-4-web/#faq-and-troubleshooting), navigate to the pre-built "Set Configuration Fields" mapping and map `properties.url` to the "Page Location", as shown here:

![](https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/u7Ah2smOfh73TOgmBCB5G_image.png)

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

## Including locale in 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.&#x20;

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](https://shopify.dev/docs/api/web-pixels-api/standard-api/browser) 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](https://shopify.dev/docs/api/web-pixels-api/standard-api/browser) 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:&#x20;

```javascript
async function getMeta() {
  if (!currency) {
    currency = await browser.cookie.get('cart_currency')
  }
  
  /* START CUSTOM CODE */
  locale = await browser.cookie.get('locale');
  /* END CUSTOM CODE */
  
  return {
    i18n: {
      currency,
      locale,
    },
    ... // rest
```

## Known tracking event issues&#x20;

Chord web pixel events use the data provided by Shopify's [web pixel framework](https://shopify.dev/docs/api/web-pixels-api/standard-events). 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.

## Connecting front-end events and server events

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 CDP workspace in response to webhook triggers from Shopify.&#x20;

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. We've created a script that makes this easy. Simply add the following to your theme:

```html
<script src="https://cdn.chord.co/analytics-liquid-identifiers/v1/analytics-liquid-identifiers.min.js" defer="defer"></script>
```

If you'd like to implement this yourself instead, you need to add two attributes:

| Attribute name    | Description                                                              | Example value                          |
| ----------------- | ------------------------------------------------------------------------ | -------------------------------------- |
| `_cdpAnonymousId` | CDP 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](https://shopify.dev/docs/api/ajax/reference/cart#update-cart-attributes). 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](docId\:FYmI5G8eWB-YYpyh-GU4o) for more details.