Installing Chord Analytics

8min

To install Chord Analytics on a Shopify store, please start here: Using with Shopify.
The @chordcommerce/analytics library provides simple methods for sending tracking events to Chord from your website, with an optional debugging mode to validate event properties.
Requirements
The Chord team will provide some of the configuration option values (see below).
Installation
To install @chordcommerce/analytics, run the following command in your project directory:
Shell
npm install @chordcommerce/analytics
# or
yarn add @chordcommerce/analytics
npm install @chordcommerce/analytics
# or
yarn add @chordcommerce/analytics
﻿
Usage
Initialize @chordcommerce/analytics as follows:
TypeScript
import { ChordAnalytics } from '@chordcommerce/analytics'

const chord = new ChordAnalytics(options) // see below for configuration options

chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP
import { ChordAnalytics } from '@chordcommerce/analytics'

const chord = new ChordAnalytics(options) // see below for configuration options

chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP
﻿
Configuration
@chordcommerce/analytics can be initialized with the following options:
Property
Required
Description
cdpDomain
true
The Chord CDP domain. To be provided by the Chord team.
cdpWriteKey
true
The Chord CDP write key. To be provided by the Chord team.
debug
false
Defaults to false. When set to true, events are validated against Chord's tracking plan and errors are logged. We recommend enabling this for development and disabling for production.
enableLogging
false
Defaults to true. When set to true, errors are logged using console.log.
formatters
true
Functions that are used to construct tracking events. There are two types of formatters, objects and events. formatters.objects is required. See Formatters﻿ for more details.
metadata
true
Event metadata. See below for details.
namespace
false
Defaults to chord. Changes where Chord is globally available (e.g. window.chord). Only applicable when using Chord CDP.
stripNull
false
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.
If cdpDomain and cdpWriteKey are all omitted, no tracking events are sent.
Metadata
Property
Required
Description
metadata.i18n.currency
true
The order currency in ISO 4217 currency code, uppercase. For example, USD.
metadata.i18n.locale
true
The order locale. For example, en-US.
metadata.ownership.omsId
true
A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.ownership.storeId
true
A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.ownership.tenantId
true
A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.platform.name
true
The name of the e-commerce platform used. For example, Shopify.
metadata.platform.type
true
The type of platform where the event originated. Either web or pos.
metadata.store.domain
true
The domain of the site where the event originated. For Shopify, this should be the store slug that comes before .myshopify.com.
Formatters
Formatters are Javascript functions that are used to construct tracking event properties. There are two types of formatters, objects and events. You must define object formatters. Event formatters are optional. See Chord’s documentation for more details and example formatters.
Object Formatters
A formatter must be provided for each of the four core data types that are used in Chord events. This formatter function transforms input data into the type Chord expects. See Formatters﻿ for more details on object formatters.
Property
Required
Description
formatters.objects.cart
true
A function that creates a cart object.
formatters.objects.checkout
true
A function that creates a checkout object.
formatters.objects.lineItem
true
A function that creates a line item object.
formatters.objects.product
true
A function that creates a product object.
Event Formatters
A formatter can be provided for each event. This formatter is used to transform the event properties of a specific event after Chord constructs the event, just before it's sent to the CDP. See Formatters﻿ for more details on event formatters.
Using with Typescript
Optionally, you can instantiate ChordAnalytics with a custom type argument describing your data to improve type safety for formatters and SDK functions.
For instance, if you're working with objects like cart, product, etc., from a Shopify storefront API query, you might already have types like StorefrontCart defined for the response. Instantiate ChordAnalytics with a type argument:
Text
interface ObjectTypes {
  Cart: StorefrontCart
  Checkout: StorefrontCart
  LineItem: StorefrontLineItem
  Product: StorefrontProduct
}

const chord = new ChordAnalytics<ObjectTypes>({ options })
interface ObjectTypes {
  Cart: StorefrontCart
  Checkout: StorefrontCart
  LineItem: StorefrontLineItem
  Product: StorefrontProduct
}

const chord = new ChordAnalytics<ObjectTypes>({ options })
﻿
Now, when you use an SDK method like chord.trackCartViewed({ cart }), cart has the StorefrontCart type.
Formatter types also support an optional generic type parameter for the function argument:
Text
import type { CartFormatter } from '@chordcommerce/analytics'

export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
  const { cart } = props // `cart` has type `StorefrontCart`
  return { ... }
}
import type { CartFormatter } from '@chordcommerce/analytics'

export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
  const { cart } = props // `cart` has type `StorefrontCart`
  return { ... }
}
﻿
﻿

Property	Required	Description
cdpDomain	true	The Chord CDP domain. To be provided by the Chord team.
cdpWriteKey	true	The Chord CDP write key. To be provided by the Chord team.
debug	false	Defaults to false. When set to true, events are validated against Chord's tracking plan and errors are logged. We recommend enabling this for development and disabling for production.
enableLogging	false	Defaults to true. When set to true, errors are logged using console.log.
formatters	true	Functions that are used to construct tracking events. There are two types of formatters, objects and events. formatters.objects is required. See Formatters for more details.
metadata	true	Event metadata. See below for details.
namespace	false	Defaults to chord. Changes where Chord is globally available (e.g. window.chord). Only applicable when using Chord CDP.
stripNull	false	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.

Property	Required	Description
metadata.i18n.currency	true	The order currency in ISO 4217 currency code, uppercase. For example, USD.
metadata.i18n.locale	true	The order locale. For example, en-US.
metadata.ownership.omsId	true	A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.ownership.storeId	true	A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.ownership.tenantId	true	A UUID assigned by Chord. This identifier is unique to the store, and will be the same across every environment and CDP source for a given store.
metadata.platform.name	true	The name of the e-commerce platform used. For example, Shopify.
metadata.platform.type	true	The type of platform where the event originated. Either web or pos.
metadata.store.domain	true	The domain of the site where the event originated. For Shopify, this should be the store slug that comes before .myshopify.com.

Property	Required	Description
formatters.objects.cart	true	A function that creates a cart object.
formatters.objects.checkout	true	A function that creates a checkout object.
formatters.objects.lineItem	true	A function that creates a line item object.
formatters.objects.product	true	A function that creates a product object.

Chord Commerce Event Tracking

API Reference