Custom storefront installation

custom storefront installation this guide covers adding chord event tracking to custom built storefronts, standalone websites, or commerce platforms other than shopify prerequisites before starting, ensure you have the values listed in step 1 install the package npm install @chordcommerce/analytics\@1 21 3 \# or yarn add @chordcommerce/analytics\@1 21 3 step 2 initialize the library @chordcommerce/analytics is a browser side library it requires access to window and the dom to load destination scripts, listen for events, and send tracking data it must not be initialized during server side rendering (ssr) if your framework renders pages on the server (next js, remix, nuxt, hydrogen, etc ), you must ensure chord only initializes in the browser here are several approaches option a react useeffect (recommended for react frameworks) useeffect only runs in the browser, never during ssr this is the simplest and most idiomatic approach for react based frameworks like next js and hydrogen 'use client' import { chordanalytics } from '@chordcommerce/analytics' import { createcontext, usecontext, useeffect, useref } from 'react' const chordcontext = createcontext\<chordanalytics | null>(null) export function chordprovider({ children } { children react reactnode }) { const chordref = useref\<chordanalytics | null>(null) useeffect(() => { if (!chordref current) { chordref current = new chordanalytics({ cdpdomain process env next public chord domain, cdpwritekey process env next public chord write key, formatters { objects { cart (props) => { / transform cart data / }, checkout (props) => { / transform checkout data / }, lineitem (props) => { / transform line item data / }, product (props) => { / transform product data / }, }, }, metadata { i18n { currency 'usd', locale 'en us' }, ownership { omsid process env next public chord oms id!, storeid process env next public chord store id!, tenantid process env next public chord tenant id!, }, platform { name 'custom', type 'web' }, store { domain 'your store domain' }, }, }) } }, \[]) return ( \<chordcontext provider value={chordref current}> {children} \</chordcontext provider> ) } export function usechord() { return usecontext(chordcontext) } then wrap your app in \<chordprovider> and use the usechord() hook in any component that needs to send tracking events option b next js dynamic import with ssr false this prevents the chord module from being imported on the server entirely useful when you want to isolate all chord logic in a single component import dynamic from 'next/dynamic' const chordprovider = dynamic(() => import(' /chordprovider'), { ssr false }) export default function layout({ children }) { return ( \<chordprovider> {children} \</chordprovider> ) } option c typeof window guard the simplest approach for non react frameworks or plain javascript check for the browser environment before initializing import { chordanalytics } from '@chordcommerce/analytics' if (typeof window !== 'undefined') { window\ chord = new chordanalytics({ cdpdomain 'your chord domain', cdpwritekey 'your chord write key', // rest of config }) } important the formatter examples above are illustrative you must map your platform's specific data structures to the fields expected by the chord tracking plan see configuration for detailed formatter documentation step 3 add tracking calls once initialized, use the sdk methods to track commerce events // page views chord page() // product interactions chord trackproductviewed({ cart, product { product, quantity 1 } }) chord trackproductadded({ cart, product { product, quantity 1 } }) chord trackproductremoved({ cart, lineitem }) // cart chord trackcartviewed({ cart }) // checkout chord trackcheckoutstarted({ checkout }) chord trackpaymentinfoentered({ checkoutid, step 1, paymentmethod 'credit card' }) // orders chord trackordercompleted({ orderid 'ord 123', orderdate '2026 03 09', currency 'usd', revenue 89 99, total 99 99, products \[{ / / }], }) // user identity chord identify(userid, { email 'user\@example com' }) see for the complete list of tracking methods and their parameters step 4 add environment variables chord domain=https //your chord domain chord write key=your write key chord oms id=your oms id chord store id=your store id chord tenant id=your tenant id typescript support the library supports generic type parameters for improved type safety interface myobjecttypes { cart mycarttype checkout mycheckouttype lineitem mylineitemtype product myproducttype } const chord = new chordanalytics\<myobjecttypes>(options) // now chord trackproductviewed expects { product myproducttype } verifying the installation set debug true in your configuration options during development this validates events against the tracking plan and logs warnings for missing or incorrect properties check the browser console for chord event logging verify events appear in the chord live events view