Event tracking with Atomic

This is for:

Developer
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 to analyze storefront performance, create reports, and power Coveo Machine Learning (Coveo ML) models. You can do this by sending events to the Coveo Analytics service.

Event tracking in Atomic for commerce uses the Event Protocol, which is a flexible and efficient way to send analytics events to Coveo. Some events can be tracked using Atomic components directly, while others require Headless. To ensure your Atomic interface and your Headless controllers are synced, 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.

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.
2 Access token is a search token or an API key that grants the Allowed access level on the Execute queries domain and the Push access level on the Analytics data domain in the target organization.

To improve security, client-side specification of user IDs isn’t supported by Event Protocol. To specify user IDs, enforce them through search tokens.
3 Via the analytics object, specify the tracking ID.
4 The context object contains information about the user’s context, such as the currency, country, language, and the URL.

Every time the user navigates between pages, you must update this URL.
5 Pass in the initial state of the cart by specifying the CartInitialState 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.

For more details on how an engine is initialized in an actual project, see the sample in the Headless repository

Initialize the Atomic commerce interface with the Headless commerce engine

On pages that have Atomic for commerce components, pass your commerce engine to your atomic-commerce-interface using the initializeWithEngine property.

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:

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

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

  );
};

Tracking click events

The atomic-product-link component automatically sends click events 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.

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.

Event Tracking controller

Product view

Use the ProductView controller to log view event when a user navigates to a PDP.

Cart

Use the Cart controller to update cart state when products are added or removed.

Purchase

Use the Cart controller to submit a purchase after a transaction is completed.