Installing Chord Analytics

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 @chordcommerce/analytics is intended to be installed alongside a customer data platform (cdp) tracking library like segment's analytics js https //www npmjs com/package/@segment/analytics next @chordcommerce/analytics sends chord tracking events to the cdp tracking library, so they’re available for all connected integrations requirements chord's analytics library assumes that a cdp javascript library is already installed on the site segment's analytics js https //segment com/docs/connections/sources/catalog/libraries/website/javascript/ library is currently the only supported option you can install analytics js either via a code snippet https //segment com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step 2b add the segment snippet or npm package https //segment com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step 2a install segment as a npm package that segment offers you'll pass a reference to the analytics object created by segment's analytics js https //segment com/docs/connections/sources/catalog/libraries/website/javascript/ library when you configure chord tracking installation to install @chordcommerce/analytics , run the following command in your project directory npm install @chordcommerce/analytics \# or yarn add @chordcommerce/analytics usage first, ensure that a cdp javascript library is installed and configured in your project then, initialize @chordcommerce/analytics as follows 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 once loaded, window\ chord will be available in the browser and will contain the chordanalytics instance configuration @chordcommerce/analytics can be initialized with the following options property required description cdp true 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 https //www npmjs com/package/@segment/analytics next library, this could be window\ analytics or () => window\ analytics if omitted, no tracking events are sent 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 docid\ jtvwpdz7 ocapd7glemid for more details metadata true event metadata see below for details 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 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 segment 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 segment 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 segment 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 https //docs chord co/analytics getting started#fgwx7 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 docid\ jtvwpdz7 ocapd7glemid 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 docid\ jtvwpdz7 ocapd7glemid 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 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 import type { cartformatter } from '@chordcommerce/analytics' export const cartformatter cartformatter\<storefrontcart> = (props) => { const { cart } = props // `cart` has type `storefrontcart` return { } }