---
title: Event tracking with Atomic
slug: p9499444
canonical_url: https://docs.coveo.com/en/p9499444/
collection: coveo-for-commerce
source_format: adoc
---
# Event tracking with Atomic
> **Important**
>
> Atomic for Commerce components are in open beta and remain under active development.
> 
> Atomic for Commerce hasn't yet gone through a formal accessibility review.
> If you have accessibility needs, contact your customer success manager and we'll work with you to address them.
It's crucial that you track [touchpoints](https://docs.coveo.com/en/o6ha0421/) to analyze [storefront](https://docs.coveo.com/en/p33g0410/) performance, create reports, and power [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/).
You can do this by sending events to the [Coveo Analytics](https://docs.coveo.com/en/182/) service.

Event tracking in [Atomic](https://docs.coveo.com/en/lcdf0264/) for commerce uses the [Event Protocol](https://docs.coveo.com/en/o1n91230/), which is a flexible and efficient way to send analytics events to Coveo.
Some events can be tracked using [Atomic](https://docs.coveo.com/en/lcdf0264/) components directly, while others require [Headless](https://docs.coveo.com/en/lcdf0493/).
To ensure your Atomic interface and your Headless controllers are synchronized, initialize your commerce interface with your Headless commerce engine.


## Initialize the Headless commerce engine

> **Tip**
>
> All controllers must depend on a single `CommerceEngine` instance.
> This instance is responsible for managing the state across all commerce solutions (such as search, recommendations, listings).

For more details on the initialization options given below, see [`buildCommerceEngine`](https://docs.coveo.com/en/headless/latest/reference/functions/Commerce.buildCommerceEngine.html).

```ts
import { buildCommerceEngine } from '@coveo/headless/commerce';
import { loadCartItemsFromLocalStorage } from '../utils/cart-utils';

export const getEngine = () => {
  if (_engine !== null) {
    return _engine;
  }

  _engine = buildCommerceEngine({
    configuration: {
      organizationId: '<ORGANIZATION_ID>', <1>
      accessToken: '<ACCESS_TOKEN>', <2>
      analytics: { <3>
        trackingId: '<TRACKING_ID>'
      },
      context: { <4>
        currency: '<CURRENCY>',
        country: '<COUNTRY>',
        language: '<LANGUAGE>',
        view: {
          url: '<URL>'
        },
      }
      cart: {
        items: loadCartItemsFromLocalStorage() ?? [], <5>
      },
    },
  });

  return _engine;
};
```
<1> Organization ID is the [unique identifier of your Coveo organization](https://docs.coveo.com/en/n1ce5273/).
<2> Access token is a [search token](https://docs.coveo.com/en/56/) or an [API key](https://docs.coveo.com/en/105/) that grants the **Allowed** [access level](https://docs.coveo.com/en/2818/) on the [**Execute queries**](https://docs.coveo.com/en/1707#execute-queries-domain) [domain](https://docs.coveo.com/en/2819/) and the **Push** [access level](https://docs.coveo.com/en/2818/) on the [**Analytics data**](https://docs.coveo.com/en/1707#analytics-data-domain) [domain](https://docs.coveo.com/en/2819/) in the target [organization](https://docs.coveo.com/en/185/).

To improve security, client-side specification of user IDs isn't supported by Event Protocol.
To specify user IDs, enforce them through [search tokens](https://docs.coveo.com/en/56/).
<3> Via the [`analytics`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Commerce.AnalyticsConfiguration.html) object, specify the [tracking ID](https://docs.coveo.com/en/o8rb0139/).
<4> The [`context`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Commerce.ContextOptions.html) object contains information about the user's context, such as the currency, country, language, and the URL.

Every time the user [navigates between pages](https://docs.coveo.com/en/o7v87331/), you must update this URL.
<5> Pass in the initial state of the cart by specifying the [`CartInitialState`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Commerce.CartInitialState.html) object.

In this code sample, a custom `loadCartItemsFromLocalStorage` function is used to initialize the cart state by fetching the cart items from local storage.
Learn more about how to [manage the cart state](https://docs.coveo.com/en/o7v87042/).


For more details on how an engine is initialized in an actual project, see [the sample in the Headless repository](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-commerce-react/src/context/engine.ts)


## Initialize the Atomic commerce interface with the Headless commerce engine

On pages that have [Atomic](https://docs.coveo.com/en/lcdf0264/) for commerce components, pass your commerce engine to your `atomic-commerce-interface` using the `initializeWithEngine` [property](https://docs.coveo.com/en/p4ue0547/).

```ts
const engine = getEngine();
const atomicCommerceInterface = document.querySelector('#id-of-the-commerce-interface');
atomicCommerceInterface.initializeWithEngine(engine);
```

If you're using React, you can pass the engine like this:

```tsx
import { AtomicCommerceInterface } from '@coveo/atomic-react';

const MyComponent = () => {
  return (
    <AtomicCommerceInterface engine={getEngine()} type="search">
        ... other components ...
    </AtomicCommerceInterface>

  );
};
```

## Tracking click events

The [`atomic-product-link`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-product-link\--docs) component automatically sends [click events](https://docs.coveo.com/en/o1n92447/) when a user clicks a product link.

The following components also automatically track click events when using the default `atomic-product-template`, because it contains an `atomic-product-link`, which automatically sends event when clicked.
If you're using a custom template and want to track click events for those components, include an `atomic-product-link` in your template.

* [`atomic-commerce-product-list`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-commerce-product-list\--docs)

* [`atomic-commerce-recommendation-list`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-commerce-recommendation-list\--docs)

* [`atomic-commerce-search-box-instant-products`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-commerce-search-box-instant-products\--docs)


## Tracking product view, cart, and purchase events

Product view, cart, and purchase events should be tracked with Headless controllers.

The following table shows the types of events to track and the corresponding Headless controllers.

[%header,cols="2*"]
|===
|Event
|Tracking controller

|[Product view](https://docs.coveo.com/en/o1n93101/)
|[Use the `ProductView` controller to log view event when a user navigates to a PDP](https://docs.coveo.com/en/o8ce0239#displaying-a-product-on-a-product-detail-page).

|[Cart](https://docs.coveo.com/en/o1n93466/)
|[Use the `Cart` controller to update cart state when products are added or removed](https://docs.coveo.com/en/o7v87042#modify-the-cart-state-on-user-interaction).

|[Purchase](https://docs.coveo.com/en/o1n93059/)
|[Use the `Cart` controller to submit a purchase after a transaction is completed](https://docs.coveo.com/en/o7v87042#modify-the-cart-state-on-user-interaction).
|===