Installing in a Shopify Theme
Chord's Shopify theme analytics library assumes that a CDP Javascript library is already installed on the site. Segment's analytics.js library is currently the only supported option. You can install Segment's analytics.js by pasting Segment's code snippet into the <head> tag of your theme. It should be added to every page of the site, so you'll likely choose to include it in layout/theme.liquid and layout/checkout.liquid (if using).
See Segment's instructions for adding the code snippet. You can find the latest version of the Segment snippet in the Overview tab of your Javascript source in your Segment workspace.
Remove analytics.page(); from the snippet after you paste it into your theme. Chord will handle calling analytics.page(); and add some extra metadata.
In the theme code, add create a Liquid file called snippets/chord.liquid and paste in this code:
Before the code is deployed to production, there are four variables at the top of the snippet that need to be updated with different values:
The value of STORE_DOMAIN should be the Shopify store name that comes before .myshopify.com. For example, if the store is https://chord-store.myshopify.com, it should be chord-store.
Chord will provide the values for the other three variables.
Include the Chord snippet on every page of the Shopify theme by rendering it inside the <head> tag in layout/theme.liquid:
To add tracking events to Shopify checkout and send an "Order Completed" tracking event from the order confirmation page, render the Chord snippet inside the <head> tag on layout/checkout.liquid, with the order_completed variable set to true:
Chord tracking cannot currently be installed on Shopify checkouts that have been upgraded to Checkout Extensibility.
Without any further code changes to your theme, Chord's snippet will send the CDP:
- A page event for every page view
- An identify event for every page view for a logged in user
- The following track events:
- "Cart Viewed"
- "Checkout Started"
- "Email Captured"
- "Order Completed" (if Chord's snippet is added to checkout.liquid)
- "Product Clicked"
- "Product Viewed"
You can add more events using the global window.chord object. See the Shopify Theme API Reference for a complete list of available methods. You can also customize the DOM selectors used for the track events that Chord automatically sends.
Chord's Liquid tracking library can be configured with the following options. To modify the default options, change the options object argument passed to chord.load():
Property | Type | Required | Description |
autoInstrument | boolean | no | Defaults to true. When set to false, track events are not automatically sent. |
autoInstrumentSelectors | object (see Auto-Instrument Selectors below) | no | Provide custom DOM selectors for automatic instrumentation of events. |
baseUrl | string | no | The base URL of the Shopify site, to use in Shopify Ajax API requests. Ex. https://example.myshopify.com. If not provided, the current origin will be used. |
cdp | function or object | yes | A reference to the CDP library, or a function that returns a reference to the CDP library. For example, if using Segment's analytics.js library, this could be window.analytics or () => window.analytics. If omitted, no tracking events are sent. |
debug | boolean | no | Defaults to false. When set to true, events are validated against Chord's tracking plan. An error is logged using console.log if the event doesn't match the tracking plan and the enableLogging option is set to true. We recommend enabling debug and enableLogging for development and disabling for production. |
enableLogging | boolean | no | Defaults to true. When set to true, Javascript and debug errors are logged using console.log. We recommend enabling debug and enableLogging for development and disabling for production. |
metadata | object (see Metadata below) | yes | Event metadata. See below for details. |
stripNull | boolean | no | Defaults to true. When set to true, event properties with a null value are removed. CDPs typically treat null and undefined as separate values, so be sure you intend to send null values before setting to false. |
syncIdentifiers | object (see Sync Identifiers below) | no | Enable adding integration identifiers as cart attributes, so they can be included in server-side events. Each integration defaults to false. |
Auto-Instrument Selectors
This optional object allows you to customize the DOM selector that Chord uses to automatically track certain events. Events related to page view, such as "Cart Viewed," aren't configurable here, because they are based on the current URL instead of an interaction with the page.
Each event property can be a boolean or a string. When set to false, Chord won't send that event automatically. To customize the DOM element that triggers the event, set the matching event property to the DOM selector you want to use. That selector will be passed to document.querySelectorAll(selector) and an event listener will be added that the library will use to trigger the event. If the selector is a <form> element, the event will be triggered when the form is submitted. Otherwise, the event will be triggered when the element is clicked.
Property | Type | Required | Description |
autoInstrumentSelectors['Checkout Started'] | string or boolean | no | The default selector is form[action="/cart" i][method="post"]. |
autoInstrumentSelectors['Email Captured'] | string or boolean | no | The default selector is form[action="/contact#contact_form" i][method="post"], form[action="/contact#contactform" i][method="post"]. |
autoInstrumentSelectors['Product Clicked'] | string or boolean | no | The default selector is a[href*="/products/" i]. |
Metadata
This required object provides metadata about the event context that is appended to every event. Chord uses this metadata when providing insights.
Property | Type | Required | Description |
metadata.i18n.currency | string | yes | The order currency in ISO 4217 currency code, uppercase. For example, USD. |
metadata.i18n.locale | string | yes | The order locale. For example, en-US. |
metadata.ownership.omsId | string | yes | A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and Segment source for a given store. |
metadata.ownership.storeId | string | yes | A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and Segment source for a given store. |
metadata.ownership.tenantId | string | yes | A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and Segment source for a given store. |
metadata.platform.name | string | yes | The name of the e-commerce platform used. For example, Shopify. |
metadata.platform.type | string | yes | The type of platform where the event originated. Either web or pos. |
metadata.store.domain | string | yes | The store slug that comes before .myshopify.com. |
Sync Identifiers
This optional object allows Chord's library to save identifiers from other libraries and integrations as attributes on the cart. Chord will use these attributes to connect your front-end website events with your server events. Read more about this in Unifying Data Across Sources.
Each integration defaults to false. Set the integration to true if you plan to send both front-end and server events to the integration via the CDP.
Currently, only the Google Analytics 4 identifier is supported. Contact Chord to request help adding more identifiers.
Property | Type | Required | Description |
syncIdentifiers['Google Analytics 4'] | boolean | no | When set to true, adds the client ID from the _ga cookie as a cart attribute. Chord will include this client ID on server events for the order, so sessions can be tied together in GA4. |