Adding Tracking
Chord sends events to Segment from the OMS and JavaScript SDKs. You need to install Segment's tracking library and add some SDK functions to your website to get events flowing.
Chord's JavaScript SDKs require installing Segment's Analytics.js tracking library on your website. First, you'll need your source write key. The write key determines which source your events will be sent to in Segment.
To locate your write key, navigate to your front-end website source in Segment and select Settings > API Keys. Typically you'll have different front-end website sources for development, staging, and production, so make sure you're selecting the correct source. Never send data to your production source except for your production website.
Next, install Analytics.js via one of the following methods:
Copy and paste the Segment snippet into the <head> tag of your site. This snippet loads and initializes Segment asynchronously. You'll need to replace YOUR_WRITE_KEY in the snippet with the write key for your Segment front-end website source.
Install @segment/snippet from npm
Instructions for installing from npm are available in the Github repo.
Segment's other npm package, analytics-next, is not supported by either Chord's SDKs or Segment's Consent Manager. Chord's SDKs use Segment's Typewriter client to send events to Segment, and Typewriter is not currently compatible with analytics-next.
Several JavaScript frameworks have examples or plugins to make this installation easier.
Next.js: Official example
Gatsby: Community plugin
Chord's JavaScript SDKs automatically send some tracking events from your website to Segment. For example, you might see this code in a button:
The addToCart function makes a request to the Chord API to update the customer's cart, updates the cart object with the new cart contents, and then sends a Product Added event to Segment with information about the product that was added.
Some SDK functions exist just to send tracking events to Segment for UI interactions. These functions are available via the useAnalytics hook and are always prefixed with track. Add these functions to your UI components to track customer interactions.
For example, to track when a customer views the shopping cart, you might add this code to your cart component:
If you don't add trackCartViewed to your UI component, this tracking event will not be sent to Segment. We recommend reviewing the useAnalytics SDK reference and adding all applicable functions to your website code.
The table below lists all tracking events that are supported by @chordcommerce/react-autonomy, and the SDK method that results in the tracking event being sent. Where possible, the SDK sends events automatically as part of standard ecommerce interactions like adding something to the cart (e.g., useCart().addToCart).
Tracking Event | @chordcommerce/react-autonomy SDK Method |
|---|---|
Login Started | useAuth().login |
Signed In | useAuth().login |
Signed Out | useAuth().logout |
Coupon Entered | useCart().addPromoCode |
Coupon Applied | useCart().addPromoCode |
Coupon Denied | useCart().addPromoCode |
Coupon Removed | useCart().removePromoCode |
Product Clicked | useAnalytics().trackCartViewed |
Collection Clicked | useAnalytics().trackCollectionClicked |
Product Added | useCart().addToCart |
Product Removed | useCart().removeFromCart |
Stock Request Created | useCart().createStockRequest |
Email Captured | useAnalytics().trackEmailCaptured |
Cart Viewed | useAnalytics().trackCartViewed |
Checkout Started | useCheckout().prepareCheckout |
Checkout Completed | useCheckout().finalizeCheckout |
Order Completed | useCheckout().finalizeCheckout |
Subscription Added | useCart().addSubscription |
Prepaid Subscription Added | useCart().addSubscription |
Subscription Cancelled | useSubscription().cancelSubscription |
Subscription Skipped | useSubscription().skipSubscription |
Subscription Resumed | useSubscription().resumeSubscription |
Subscription Paused | useSubscription.pauseSubscription |
Product Viewed | useAnalytics().trackProductViewed |
Variant Clicked | useAnalytics().trackVariantClicked |
For more examples of instrumenting your UI components, review Chord's website starter kits.
After you've installed Segment's Analytics.js library and added some SDK functions to your UI components, verify that Segment is receiving tracking events.
In Segment, navigate to your website front-end source, and select the Debugger tab. This shows you a live feed of tracking events that Segment is receiving.
Interact with your website, and you should see new events appear in the Debugger. Inspect the contents of an event by selecting it. Note that events have different types, including Page, Track, and Identify.
Complete this checklist to verify Segment has been installed correctly on your website.
The correct source shows your events. Events from development and staging environments should not appear in your production source, and vice versa.
The back-end source shows Track events. For example, you should see an Order Completed event when an order is completed. You should see all events in The Chord Tracking Plan marked as sent by the OMS.
The front-end source shows Track events. For example, you should see a Product Added event when a product is added to your shopping cart, and a Cart Viewed Event when you view the cart page. You should see all events in The Chord Tracking Plan marked as sent by the SDK, unless they are UI events that you Adding Tracking.
The front-end source shows Page events.
Initial page load sends a Page event.
Clicking an internal link sends a Page event.
The front-end source shows Identify events when a customer enters an email address. For example, you should see an Identify event when a customer fills out a newsletter sign-up form.
I'm not seeing any events in the back-end source.
The OMS might be sending events to a different back-end source than you're expecting. Log into your OMS admin, and navigate to Settings > Stores. In the Environment Variables section, look for SEGMENT_WRITE_KEY. The write key determines the source that events are sent to.
I'm not seeing any events in the front-end source.
Check that the write key in your website code is for the correct front-end source. Next, try following Segment's troubleshooting guide for Analytics.js.
I only see a Page event when the site first loads, not when I click around.
Many frameworks like Next.js handle page transitions for internal links with JavaScript, which sometimes needs to be explicitly configured to generate a Page event. For example, here's how the Chord Next.js starter handles it.
if you have any questions or need help, please reach out to us at [email protected]