Shopify installation

this guide covers adding chord event tracking to any shopify store — liquid themes, hydrogen, or custom headless storefronts the setup has three parts add @chordcommerce/analytics to your storefront — loads the tracking library on your site add the custom web pixel in shopify admin — tracks checkout events and, for liquid themes, storefront events enable server event tracking via webhooks — tracks server side events such as order creations and order refunds adding all three elements ensures that all events, from browsing through checkout — including on shopify's hosted checkout pages, are tracked in chord due to technical limitations within shopify, the chord analytics package does not load on shop pay pages prerequisites before starting, ensure you have the values listed in how it works chord tracking on shopify uses two components that work together @chordcommerce/analytics runs on your storefront pages and sends tracking events to chord it also loads any device mode destination scripts (such as google analytics or meta pixel) directly in the browser additionally, it listens for events forwarded from the custom web pixel the custom web pixel runs within shopify's event system, where it subscribes to all customer events (page views, add to cart, checkout steps, order completion) for storefront events, the web pixel forwards them to a listener on the top window within @chordcommerce/analytics , which processes the event and delivers it to chord and any configured destinations (device mode and cloud mode) for checkout events that occur on shopify hosted pages, the web pixel sends them directly to chord via cloud mode this architecture ensures complete event coverage — storefront interactions, shopify hosted checkout pages, and post purchase events are all captured through a single, unified pipeline note due to technical limitations in shopify, device mode destinations (scripts that run in the browser) cannot be loaded or executed on shopify hosted pages these pages include checkout order status thank you page events on these pages are delivered exclusively via cloud mode storefront pages are not affected — device mode destinations load and execute normally there step 1 add @chordcommerce/analytics to your storefront option a liquid theme for stores using a standard shopify liquid theme, add the chord analytics snippet to your theme in your shopify admin, go to online store > themes > edit code create a new snippet called chord liquid and paste the following //instantiates analytics liquid identifiers, which handles reading/pasing of cookies to shopify cart attributes \<script src='https //cdn chord co/analytics liquid identifiers/v1/analytics liquid identifiers min js' defer='defer' \>\</script> //instantiates chord analytics \<script type="module"> import { chordanalytics } from 'https //cdn jsdelivr net/npm/@chordcommerce/analytics\@1 22 1/+esm' window\ chord = new chordanalytics({ cdpdomain 'https //production cdp ingest chord co', cdpwritekey 'your chord write key', 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> in layout/theme liquid , add the following before the closing \</body> tag {% render 'chord' %} option b hydrogen / headless storefront for hydrogen or other javascript based storefronts, install the npm package install the package initialize the library in your root layout or app entry point add your environment variables see for the full list of options, and for tracking methods you can call from your storefront code step 2 add the custom web pixel the custom web pixel subscribes to all shopify customer events and tracks events on shopify hosted pages, such as checkout specifically for each platform liquid themes all storefront and checkout tracking headless storefronts checkout tracking only (storefront events are handled by your sdk integration in step 1) installation in your shopify admin, go to settings > customer events click add custom pixel name the pixel (e g , "chord") paste the web pixel code provided by the chord team the code includes configuration constants at the top that must be filled in under customer privacy , select does not require consent (consent is managed by @chordcommerce/analytics — see ) click save , then click connect to activate the pixel verifying the installation after installing both components, open your browser's developer console and verify on a storefront page (e g , a product page) you should see chord network requests when browsing products, adding to cart, etc on the checkout page checkout events (checkout started, payment info entered, order completed) should appear in your chord live events view tip set debug true in your @chordcommerce/analytics configuration during development this validates events against the tracking plan and logs warnings for missing or incorrect properties step 3 enable server event tracking in addition to front end tracking, chord can receive server side events from shopify via webhooks this enables tracking for events that occur outside the browser, such as order refunds see docid\ xbl7zbqe14bt7gbtml0un for setup instructions troubleshooting events not appearing in chord verify the domain and write key are correct in both the analytics library and the web pixel check the browser console for error messages from chord ensure the web pixel status is "connected" in shopify admin > customer events storefront events missing (liquid themes) confirm {% render 'chord' %} is in your theme liquid layout check the browser console for script loading errors from jsdelivr checkout events missing verify the web pixel is connected (not just saved) in shopify admin check that the credentials in the web pixel match your analytics library configuration