Formatters

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 object formatters 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 available object formatters method type description cart (props cartinput ) => cart returns a chord cart object checkout (props checkoutinput ) => checkout returns a chord checkout object lineitem (props lineiteminput ) => lineitem returns a chord lineitem object product (props productinput ) => product returns a chord product object example object formatter 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 var cart = await getcartfromshopifystorefrontapi() // the `cart` object here can be any type chord trackcartviewed({ cart }) 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 https //shopify dev/docs/api/storefront/2023 10/objects/cart into chord's cart object import { cartinput, cart, chordanalytics } from '@chordcommerce/analytics' const cartformatter (props cartinput) => cart = ({ cart }) => { const products = cart? lines? map((line, i) => { const lineitem = line? node return { lineitemformatter({ lineitem }), // your `lineitem` formatter position i + 1, } }) return { cart id cart? id? replace('gid //shopify/cart/', ''), currency 'usd', products, value number(cart? cost? subtotalamount? amount) || 0, } } // when creating an instance of `chordanalytics`, set `formatters objects cart` to `cartformatter` const chord = new chordanalytics({ formatters { objects { cart cartformatter, }, } }) event formatters 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 available event formatters 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 method type description cartviewed (props cartviewedinput, event cartviewed) => cartviewed event triggered when a cart is viewed checkoutstarted (props checkoutstartedinput, event checkoutstarted) => checkoutstarted event triggered when the checkout process starts couponapplied (props couponappliedinput, event couponapplied) => couponapplied event triggered when a coupon is successfully applied coupondenied (props coupondeniedinput, event coupondenied) => coupondenied event triggered when a coupon is denied couponentered (props couponenteredinput, event couponentered) => couponentered event triggered when a coupon code is entered couponremoved (props couponremovedinput, event couponremoved) => couponremoved event triggered when a coupon is removed emailcaptured (props emailcapturedinput, event emailcaptured) => emailcaptured event triggered when an email is captured productadded (props productaddedinput, event productadded) => productadded event triggered when a product is added to the cart productclicked (props productclickedinput, event productclicked) => productclicked event triggered when a product is clicked productlistfiltered (props productlistfilteredinput, event productlistfiltered) => productlistfiltered event triggered when a product list is filtered productlistviewed (props productlistviewedinput, event productlistviewed) => productlistviewed event triggered when a product list is viewed productremoved (props productremovedinput, event productremoved) => productremoved event triggered when a product is removed from the cart productviewed (props productviewedinput, event productviewed) => productviewed event triggered when a product is viewed productssearched (props productssearchedinput, event productssearched) => productssearched event triggered when products are searched signedin (props signedininput, event signedin) => signedin event triggered when a user signs in signedout (props signedoutinput, event signedout) => signedout event triggered when a user signs out signedup (props signedupinput, event signedup) => signedup event triggered when a user signs up example event formatter 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 chord tracksignedin({ email 'hello\@chord co', button 'purple' }) 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 import { cartinput, cart, chordanalytics } from '@chordcommerce/analytics' const signedinformatter (props signedininput, event signedin) => signedin = (props, event) => { return { event, button props button } } const chord = new chordanalytics({ formatters { events { signedin signedinformatter, }, } })