UNPKG

@chordcommerce/analytics

Version:

Chord Commerce event tracking

120 lines (81 loc) • 9.59 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# @chordcommerce/analytics The `@chordcommerce/analytics` library provides simple methods for sending tracking events to Chord from your website, with an optional debugging mode to validate event properties. Visit [docs.chord.co](https://docs.chord.co/installing-chord-analytics) for guides, examples, and an API reference. ## Requirements The library supports sending events via Chord CDP or Segment. If using Segment, [analytics.js](https://www.npmjs.com/package/@segment/analytics-next) must also be installed in your project. ## Installation To install `@chordcommerce/analytics`, run the following command in your project directory: ```bash npm install @chordcommerce/analytics # or yarn add @chordcommerce/analytics ``` ## Usage Initialize `@chordcommerce/analytics` as follows: ```jsx import ChordAnalytics from '@chordcommerce/analytics' const chord = new ChordAnalytics(options) // see below for configuration options chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP ``` ## Configuration `@chordcommerce/analytics` can be initialized with the following options: | Property | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cdp` | false | _Required when using a CDP other than Chord._ A reference to the CDP library, or a function that returns a reference to the CDP library. For example, if using Segment's [analytics.js](https://www.npmjs.com/package/@segment/analytics-next) library, this could be `window.analytics` or `() => window.analytics`. | | `cdpDomain` | false | _Required when using Chord CDP._ The Chord CDP domain. To be provided by the Chord team. | | `cdpWriteKey` | false | _Required when using Chord CDP._ The Chord CDP write key. To be provided by the Chord team. | | `debug` | false | Defaults to `false`. When set to `true`, events are validated against Chord's tracking plan and errors are logged. We recommend enabling this for development and disabling for production. | | `enableLogging` | false | Defaults to `true`. When set to `true`, errors are logged using `console.log`. | | `formatters` | true | Functions that are used to construct tracking events. There are two types of formatters, objects and events. `formatters.objects` is required. See below for details. | | `metadata` | true | Event metadata. See below for details. | | `namespace` | false | Defaults to `chord`. Changes where Chord is globally available (e.g. `window.chord`). _Only applicable when using Chord CDP._ | | `stripNull` | false | Defaults to `true`. When set to `true`, event properties with a `null` value are removed. CDPs typically treat `null` and `undefined` as separate values, so be sure you intend to send `null` values before setting to false. | If `cdp`, `cdpDomain`, and `cdpWriteKey` are all omitted, no tracking events are sent. **Metadata** | Property | Required | Description | | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `metadata.i18n.currency` | true | The order currency in ISO 4217 currency code, uppercase. For example, `USD`. | | `metadata.i18n.locale` | true | The order locale. For example, `en-US`. | | `metadata.ownership.omsId` | true | A UUID assigned by Chord. | | `metadata.ownership.storeId` | true | A UUID assigned by Chord. | | `metadata.ownership.tenantId` | true | A UUID assigned by Chord. | | `metadata.platform.name` | true | The e-commerce platform used. For example, `Shopify`. | | `metadata.platform.type` | true | The type of platform where the event originated. Either `web` or `pos`. | | `metadata.store.domain` | true | The domain of the site where the event originated. For Shopify, this should be the store slug that comes before `.myshopify.com`. | ### Formatters Formatters are Javascript functions that are used to construct tracking event properties. There are two types of formatters, objects and events. You must define object formatters. Event formatters are optional. See [Chord’s documentation](https://docs.chord.co/analytics-getting-started#fgWx7) for more details and example formatters. **Object Formatters** A formatter must be provided for each of the four core data types that are used in Chord events. This formatter function transforms input data into the type Chord expects. See [Chord’s documentation](https://docs.chord.co/analytics-getting-started#XhUB5) for more details on object formatters. | Property | Required | Description | | ----------------------------- | -------- | ------------------------------------------- | | `formatters.objects.cart` | true | A function that creates a cart object. | | `formatters.objects.checkout` | true | A function that creates a checkout object. | | `formatters.objects.lineItem` | true | A function that creates a line item object. | | `formatters.objects.product` | true | A function that creates a product object. | **Event Formatters** A formatter can be provided for each event. This formatter is used to transform the event properties of a specific event after Chord constructs the event, just before it's sent to the CDP. See [Chord’s documentation](https://docs.chord.co/analytics-getting-started#jquZe) for more details on event formatters. ## Using with Typescript Optionally, you can instantiate `ChordAnalytics` with a custom type argument describing your data to improve type safety for formatters and SDK functions. For instance, if you're working with objects like `cart`, `product`, etc., from a Shopify storefront API query, you might already have types like `StorefrontCart` defined for the response. Instantiate `ChordAnalytics` with a type argument: ```js interface ObjectTypes { Cart: StorefrontCart Checkout: StorefrontCart LineItem: StorefrontLineItem Product: StorefrontProduct } const chord = new ChordAnalytics<ObjectTypes>({ options }) ``` Now, when you use an SDK method like `chord.trackCartViewed({ cart })`, `cart` has the `StorefrontCart` type. Formatter types also support an optional generic type parameter for the function argument: ```js import type { CartFormatter } from '@chordcommerce/analytics' export const cartFormatter: CartFormatter<StorefrontCart> = (props) => { const { cart } = props // `cart` has type `StorefrontCart` return { ... } } ``` ## API Reference See [Chord’s documentation](https://docs.chord.co/api-reference) for a full API reference. ## Support For support with setup and configuration, please contact Chord directly at **help@chord.co**.