Formatters are Javascript functions that are used to construct tracking event data. There are two types of formatters, objects and events. You must define object formatters. event formatters are optional.

When you look at Chord's tracking events, you'll see some event properties are used over and over. Names and values of event properties are expected to be consistent between events. In other words, different events have different properties, but a given property name should have the same value wherever it's used.

For example, the two events Product Added and Product Clicked share most of the same event properties. product_id is a property of both events, and the value of product_id is expected to be the same for both events. It should not be a product SKU for one event and a database identifier for another event.

Chord ensures consistency in property names and values by creating a standard set of object models that are used over and over throughout events. There are four: cart, checkout, lineItem, and product. When you install Chord's analytics library, you write a formatter function for each of these four types. Your formatter function will receive as an argument the input from the event tracking function, and your formatter must return an object in the format that Chord expects. Then Chord uses this formatter to generate the correct event payload.

Let's walk through an example of a cart formatter.

In your website code, you might want to send a Cart Viewed tracking event. The code used to send Cart Viewed looks like this:

But how does Chord create a standard Cart Viewed event when you can pass any arbitrary cart object as the value? You'll define a formatter that converts your cart object into a format that Chord understands. See the Cart Typescript type exported by @chordcommerce/analytics to see what the return type of the cart formatter should be. Here's an example of a cart formatter that converts a Shopify Storefront API cart response into Chord's Cart object:

Event formatters are optional. You can supply an event formatter for any event-specific tracking method of ChordAnalytics; for example, for chord.trackProductAdded, you can set an event formatter with the key productAdded.

Chord's library will call your event formatter after constructing the tracking event but before sending to the CDP. This is the easiest way to customize a Chord tracking event, if you're not able to get the effect you want with object formatters. A common use case is to add additional properties to a specific tracking event.

All event formatters are optional. Event formatters have two arguments: props, which is the argument passed to the related tracking function (for example, chord.trackProductClicked(props)), and event, which is the finished event payload Chord has constructed to send to the CDP.

In this example, let's add an additional property to the "Signed In" event to track whether the user signed in by clicking the yellow button or the purple button.

The code used to send "Signed In" looks like this:

As written, Chord will ignore the button property and not include it in the event sent to the CDP, because it's not part of Chord's tracking plan. To include the button property in the event, add an event formatter: