> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/collect-data/shopify/browser-events.md).

# Browser events

Browser events track what shoppers do on your storefront and in checkout: page views, product views, add to cart, checkout steps and orders. Every Shopify store needs three pieces, whether it uses a Liquid theme, Hydrogen or a custom headless build:

1. The Chord analytics package, `@chordcommerce/analytics`
2. The Chord identifiers script
3. The Chord web pixel

## How it works

The web pixel listens, and the analytics package sends.

* **The web pixel listens.** Shopify only reports shopper actions, such as product views, add to cart and checkout steps, to pixels. The analytics package can't hear them on its own.
* **The analytics package sends.** The pixel passes storefront events to the analytics package on the page. The package delivers them to Chord, runs your browser (device-mode) destinations such as Meta Pixel or GA4, and handles identity and consent.
* **Checkout is the exception.** The analytics package can't run on Shopify-hosted checkout pages, so the pixel sends checkout events to Chord itself. It also runs your device-mode destinations inside Shopify's checkout sandbox.
* **The identifiers script links sessions.** It saves the shopper's browser identifiers on the cart, so the [server events](/collect-data/shopify/server-events.md) Shopify sends later can be matched to the same shopper.

Without the pixel, Chord sees almost nothing from a Liquid store. Without the analytics package, storefront events have no way to reach Chord.

{% hint style="info" %}
Device-mode destinations run on Shopify-hosted checkout pages, with two limits:

* Shopify only loads the pixel after the shopper grants consent. See [Consent](/collect-data/shopify/browser-events/consent.md).
* Signed-in Shop Pay customers check out on shop.app, where no pixel can load.
  {% endhint %}

{% hint style="warning" %}
Because of technical limitations within Shopify, the Chord analytics package doesn't load on Shop Pay pages.
{% endhint %}

## Before you start

Ask Chord for these values:

* Your CDP domain and write key
* Your OMS ID, store ID and tenant ID
* The Chord web pixel code

## Step 1: Add the analytics package

### Liquid theme

1. In Shopify admin, go to **Online Store > Themes > Edit code**.
2. Create a new snippet called `chord.liquid` and paste in the following. Replace the `your-...` values with the ones Chord gave you.

   ```liquid
   <script type="module">
     import { ChordAnalytics } from 'https://cdn.jsdelivr.net/npm/@chordcommerce/analytics@1.24.5/+esm'

     window.chord = new ChordAnalytics({
       cdpDomain: 'https://production.cdp.ingest.chord.co',
       cdpWriteKey: 'your-chord-write-key',
       consent: 'shopify', // reads consent from Shopify's Customer Privacy API; see Consent
       debug: false,
       enableLogging: false,
       formatters: {
         objects: {
           cart: (props) => props.cart,
           checkout: (props) => props.checkout,
           lineItem: (props) => props.lineItem,
           product: (props) => props.product,
         },
       },
       metadata: {
         i18n: {
           currency: {{ cart.currency.iso_code | default: 'USD' | json }},
           locale: "{{ localization.language.iso_code | default: 'en' }}-{{ localization.country.iso_code | default: 'US' }}",
         },
         ownership: {
           omsId: 'your-oms-id',
           storeId: 'your-store-id',
           tenantId: 'your-tenant-id',
         },
         platform: {
           name: 'shopify',
           type: 'web',
         },
         store: {
           domain: 'your-store-slug',
         },
       },
     })
   </script>
   ```
3. In `layout/theme.liquid`, add the following before the closing `</body>` tag:

   ```liquid
   {% render 'chord' %}
   ```

### Hydrogen or headless storefront

Install and initialize the npm package by following [Everyone else: Browser events](/collect-data/everyone-else/browser-events.md). Those steps cover Hydrogen and other JavaScript frameworks. Set `platform.name` to `shopify` in the metadata.

## Step 2: Add the identifiers script

The identifiers script saves the shopper's browser identifiers as attributes on the Shopify cart. Shopify includes those attributes with the order, so Chord can link [server events](/collect-data/shopify/server-events.md) back to the shopper's browser session. Without it, orders from Shopify arrive in Chord with no link to the browsing that led to them.

### Liquid theme

Add this line to `layout/theme.liquid`, just before `{% render 'chord' %}`:

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

### Hydrogen or headless storefront

Load the same script on your storefront pages if your framework allows it. If not, save the identifiers on the cart yourself with Shopify's [`cartAttributesUpdate`](https://shopify.dev/docs/api/storefront/latest/mutations/cartAttributesUpdate) mutation:

* `_cdpAnonymousId`: the anonymous ID that `@chordcommerce/analytics` assigned to the shopper, from the `__eventn_id` cookie. Required.
* `_googleClientId`: the value of the `_ga` cookie with its first six characters removed. Add it if you use Google destinations.

Add the attributes before the shopper reaches checkout, at a moment that doesn't block them, such as when the cart page loads or after a product is added.

## Step 3: Add the Chord web pixel

1. In Shopify admin, go to **Settings > Customer events**.
2. Click **Add custom pixel** and name it, for example "Chord".
3. Under **Customer privacy**, set the options described in [Consent](/collect-data/shopify/browser-events/consent.md#step-1-set-the-pixels-privacy-settings).
4. Copy the [web pixel code](/collect-data/shopify/browser-events/web-pixel-code.md) into the **Code** box.
5. Update the `const` variables at the very top of the code (see the settings below), then click **Save**.
6. Click **Connect** to activate the pixel. The pixel starts tracking as soon as you connect it, so finish the settings first.

### Web pixel settings

* **`CHORD_OMS_ID`**, **`CHORD_STORE_ID`**, **`CHORD_TENANT_ID`** (string): IDs assigned by Chord. Each is unique to the store, and the same across every environment and source for that store.
* **`DEFAULT_LOCALE`** (string): the default order locale, for example `en-US`.
* **`CDP_DOMAIN`** (string): provided by Chord. The domain for your website source.
* **`CDP_WRITE_KEY`** (string): provided by Chord. The write key for your website source.
* **`STORE_DOMAIN`** (string): the store slug that comes before `.myshopify.com` in your Shopify URL.

## Verify the installation

1. Set `debug: true` and `enableLogging: true` in your analytics configuration while you test. Together they check events against the tracking plan and log warnings for missing or incorrect properties to the browser console.
2. **On a storefront page**, such as a product page: open your browser's developer console. You should see Chord network requests as you browse products and add to cart.
3. **In checkout:** place a test order. Checkout Started, Payment Info Entered and Order Completed should appear in **Live Events** in Chord.
4. Turn `debug` and `enableLogging` off again when you're done.

### Troubleshooting

**Events aren't appearing in Chord**

* Check that the domain and write key are the same in the analytics package and the web pixel.
* Check the browser console for error messages from Chord.
* Make sure the web pixel's status is **Connected** in **Settings > Customer events**.
* If you're testing from a region with a cookie banner, accept analytics and marketing cookies first.

**Storefront events are missing (Liquid themes)**

* Confirm `{% render 'chord' %}` is in your `theme.liquid` layout.
* Check the browser console for script loading errors from jsdelivr.

**Checkout events are missing**

* Make sure the web pixel is connected, not just saved.
* Check that the credentials in the web pixel match your analytics package configuration.

## Events the web pixel tracks

The pixel tracks every [standard customer event](https://shopify.dev/docs/api/web-pixels-api/standard-events) Shopify gives to pixels, with no theme code. If an interaction you care about isn't listed, Shopify doesn't publish an event for it, and you track it from your theme with the analytics package.

### Storefront events

The pixel passes these to the analytics package, which sends them to Chord and your device-mode destinations.

* `page_viewed` → a `page()` call, with path, URL and title
* `product_viewed` → [Product Viewed](/collect-data/tracking-plan/product-viewed.md)
* `collection_viewed` → [Product List Viewed](/collect-data/tracking-plan/product-list-viewed.md), with the collection's product variants
* `search_submitted` → [Products Searched](/collect-data/tracking-plan/products-searched.md), with the search query
* `cart_viewed` → [Cart Viewed](/collect-data/tracking-plan/cart-viewed.md), only on the `/cart` page (see [what the pixel doesn't track](#what-the-pixel-doesnt-track))
* `product_added_to_cart` → [Product Added](/collect-data/tracking-plan/product-added.md)
* `product_removed_from_cart` → [Product Removed](/collect-data/tracking-plan/product-removed.md)

### Checkout events

The pixel sends these to Chord itself, and runs your device-mode destinations in the checkout sandbox.

* `checkout_started` → [Checkout Started](/collect-data/tracking-plan/checkout-started.md), with line items, coupon, discount, tax and shipping
* `checkout_contact_info_submitted` → [Checkout Step Completed](/collect-data/tracking-plan/checkout-step-completed.md) (step 1), plus an `identify` with the shopper's email and phone
* `checkout_address_info_submitted` → Checkout Step Completed (step 2)
* `checkout_shipping_info_submitted` → Checkout Step Completed (step 3)
* `payment_info_submitted` → [Payment Info Entered](/collect-data/tracking-plan/payment-info-entered.md) (step 4)
* `checkout_completed` → [Order Completed](/collect-data/tracking-plan/order-completed.md), plus an `identify` with the Shopify customer ID

### Customer identification

The pixel sends an `identify` call in three situations:

1. **On load**, when Shopify reports a logged-in customer. Traits come from Shopify's customer object: email, first and last name, phone and order count.
2. **When the shopper submits contact info in checkout**, with the email and phone they entered. No user ID is set here, because an email isn't a stable identifier.
3. **When checkout completes**, with the Shopify customer ID as the user ID.

### What the pixel doesn't track

**Sign-in.** Shopify publishes no sign-in event, so a shopper who signs in mid-session isn't identified until the next page load. To identify them right away, call `window.chord.identify()` from your theme when they sign in.

**Cart drawers.** Shopify fires `cart_viewed` only when a shopper goes to `/cart`. If your theme opens the cart in a slide-out drawer, call `window.chord.trackCartViewed()` when the drawer opens.

**Merchandising interactions.** No standard event covers clicks in a collection grid, quick-add buttons, wishlist actions or variant switching. Track these from your theme code. See the [SDK reference](/collect-data/everyone-else/sdk-reference.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/collect-data/shopify/browser-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.