@chordcommerce/analytics/README.md

Chord Commerce event tracking

# @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
```

### CommonJS Import

If you are using an older version of NodeJS (<v11) or Webpack, importing using the above ES6 import will probably fail. You can instead import using CommonJS:

```jsx
const { ChordPixel } = require('@chordcommerce/analytics/dist/cjs')
```

## 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 { ... }
}
```

addSourceMiddleware(func: AnalyticsMiddleware)

Registers a middleware function to modify event properties before they are
sent to analytics providers. Middleware functions are executed
synchronously in the order they were added during event tracking.

Parameters

- func (AnalyticsMiddleware) - A middleware function that receives event
  data and can return additional properties to merge into the event payload.

Return Value

The middleware function can return:

- Partial<EventProperties> - Properties to merge into the event payload
- void - No additional properties to add

Useage Example

```
  analytics.addSourceMiddleware(({ payload }) => {
    const { searchParams } = payload.obj.context.page;

    return {
      utm_source: searchParams.utm_source,
      utm_medium: searchParams.utm_medium,
      utm_campaign: searchParams.utm_campaign
    };
  });

  analytics.addSourceMiddleware(({ payload }) => {
    return {
      session_id: getSessionId(),
      user_agent: navigator.userAgent,
      timestamp: Date.now()
    };
  });
```

## API Reference

See [Chord’s documentation](https://docs.chord.co/api-reference) for a full API reference.

## Releasing

This package uses [semantic-release](https://github.com/semantic-release/semantic-release) to automate versioning and publishing. Releases are triggered automatically — no manual version bumps or publish steps are needed.

### How it works

The repo has a single CI workflow (`.github/workflows/ci.yml`) with two jobs:

1. **`test`** — Runs lint, prettier, build, and tests for all packages. Triggers on every push to `main`/`beta` and on every pull request.
2. **`release`** — Runs only on `main` and `beta` branches, after `test` passes. Runs `semantic-release` to determine if a new version should be published.

The release flow:

1. Merge a PR into `main` (stable) or `beta` (pre-release).
2. The `test` job runs. If it passes, the `release` job starts.
3. `semantic-release` analyzes commit messages since the last release tag.
4. If releasable commits exist, the package is published to npm and GitHub Packages, CHANGELOG.md is updated, and a Git tag is created.
5. If no releasable commits exist, `semantic-release` exits cleanly and nothing is published.

### PR titles must follow conventional commits

When using GitHub's **squash merge** (the default), the PR title becomes the first line of the squash commit message. Semantic-release only parses the **first line** to determine the version bump, so **the PR title must use a conventional commit prefix** (e.g., `fix: resolve consent race condition`). Individual commit messages in the PR body are ignored.

If the PR title does not start with a releasable prefix, no release will be published even if the individual commits within the PR use `fix:` or `feat:`.

### When a release happens (and when it doesn't)

A release is published **only** when all three conditions are met:

1. A push lands on `main` or `beta` (via merged PR or direct push)
2. Tests pass
3. There are new commits since the last release tag with a releasable prefix (checked against the **first line** of each commit message)

**Releasable commit prefixes** (these trigger a version bump):

| Prefix                     | Version Bump          | Example                                                   |
| -------------------------- | --------------------- | --------------------------------------------------------- |
| `fix:`                     | Patch (1.0.0 → 1.0.1) | `fix: resolve race condition in consent adapter`          |
| `feat:`                    | Minor (1.0.0 → 1.1.0) | `feat: add trackOrderCompleted method`                    |
| `BREAKING CHANGE:` in body | Major (1.0.0 → 2.0.0) | Commit body contains `BREAKING CHANGE: remove legacy API` |

**Non-releasable prefixes** (these do NOT trigger a release):

`chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `style:`, `build:`, `perf:`

If a merge to `main` or `beta` contains only non-releasable commits, the release job runs but `semantic-release` determines no release is needed and exits without publishing.

### Monorepo scoping

This repo uses [semantic-release-monorepo](https://github.com/pmowrer/semantic-release-monorepo) to scope releases to individual packages. Only commits that touch files within a package's directory (e.g., `packages/core/`) are considered when determining the next version. A `feat:` commit that only modifies `.github/workflows/` or another package's directory will **not** trigger a release for `@chordcommerce/analytics`.

### Pre-releases

Merging to `beta` creates pre-release versions (e.g., `1.22.0-beta.1`). Use this for testing before promoting to `main`. Only `main` and `beta` are currently configured for automatic releases in the CI workflow. Additional prerelease branches (e.g., `alpha`) can be enabled by adding them to both the workflow's branch filter in `ci.yml` and the semantic-release branch config.

### Beta release workflow

1. Create a feature branch off `beta` and do your work.
2. Create a PR targeting the `beta` branch and merge it.
3. The CI workflow runs tests, then `semantic-release` publishes a beta version (e.g., `1.22.0-beta.1`).
4. Install with: `npm install @chordcommerce/analytics@beta`

### Promoting beta to production

1. Create a PR from `beta` → `main` and merge it.
2. The CI workflow runs tests, then `semantic-release` publishes a stable version on `main`.

### Dry run

You can preview what a release would do without publishing by manually triggering the CI workflow in GitHub Actions with `dryRun` set to `true`.

## Support

For support with setup and configuration, please contact Chord directly at **help@chord.co**.