Custom implementations: Track events without the Coveo app for Shopify

This is for:

Developer

In this article

Types of events
Headless
Atomic

usage analytics events are crucial for analyzing your storefront performance and power Coveo Machine Learning (Coveo ML) models. This page explains how to track commerce events if you’re not using the Coveo AI Search and Discovery app. If you’re using the app, see Track Shopify events using the Coveo AI Search & Discovery app.

Types of events

There are four types of commerce events:

Note

Under the Coveo Event Protocol (EP), the Commerce API logs search events server-side automatically for you.

Headless

The appropriate Headless controllers log click, cart, and product view events.

To log click and product view events, see Displaying products.
To log cart events, see Managing the cart.

Headless can’t log purchase events in your store. To log purchase events, implement an app web pixel that uses Coveo Relay. Whenever your store logs a checkout_completed event, the pixel triggers a corresponding purchase event, as in the following implementation example.

Create a web pixel extension and configure it as follows:

# shopify.extension.toml

name = "coveo-analytics-web-pixel"
type = "web_pixel_extension"

runtime_context = "strict"

[customer_privacy]
analytics = true 
marketing = false
preferences = false
sale_of_data = "disabled"

[settings]
type = "object"

[settings.fields.organizationId] 
name = "Organization ID"
description = "Your Coveo organization ID."
type = "single_line_text_field"
validations = [{ name = "min", value = "1" }]

	Set the `analytics` setting to `true` because the app web pixel will log analytics events.
	When activating your web pixel, you’ll pass your Coveo organization ID in the `organizationId` setting.

Install the required dependencies, namely @coveo/relay, @coveo/relay-event-types, and @coveo/shopify.

// package.json

{
  // ...
  "dependencies": {
    // ...
    "@coveo/relay": "^1.2.0",
    "@coveo/relay-event-types": "^13.1.3",
    "@coveo/shopify": "1.3.0",
  }
}

Create a helper file to build the target Coveo Relay events.

// src/ecEventsBuilders.ts

import { CurrencyCodeISO4217, ProductQuantity } from "@coveo/relay-event-types";
import { Checkout, CheckoutLineItem } from "@shopify/web-pixels-extension";
import { Ec } from "@coveo/relay-event-types";

export const ecPurchaseEvent = (checkout: Checkout): Ec.Purchase => ({ 
  currency: checkout.currencyCode?.toUpperCase() as CurrencyCodeISO4217,
  products: checkout.lineItems.map(lineItemObject),
  transaction: {
    id: checkout.token ?? "",
    revenue: checkout.totalPrice?.amount ?? 0,
  },
});

const lineItemObject = (lineItem: CheckoutLineItem): ProductQuantity => ({
  quantity: lineItem.quantity,
  product: {
    productId: lineItem.id ?? "",
    name: lineItem.title ?? "",
    price: lineItemPrice(lineItem),
  },
});

const lineItemPrice = (lineItem: CheckoutLineItem): number =>
  (lineItem.finalLinePrice?.amount ?? 0) / lineItem.quantity;

Build the purchase event.

Create a Relay environment helper file for client ID and context management. Outside of Shopify web pixels, Relay can manage the client ID and context automatically, but the restrictive nature of web pixels requires a custom implementation.

// relayEnvironment.ts

import type { CustomEnvironment } from "@coveo/relay";
import { ExtensionApi } from "@shopify/web-pixels-extension";

export const webPixelRelayEnvironment = ({ init }: ExtensionApi, clientId: string): CustomEnvironment => {
  return {
    generateUUID: () => clientId, 
    getLocation: () => init.context.document.location.href,
    getReferrer: () => init.context.document.referrer,
    getUserAgent: () => init.context.navigator.userAgent,
    send: (url, token, event) =>
      fetch(`${url}?access_token=${token}`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        keepalive: true,
        body: JSON.stringify([event]),
      }),
  };
};

This client ID will be retrieved from a coveo_shopify_config custom event emitted by the storefront, which will be handled in the next step.

Create a getCoveoShopifyEvent.ts file that listens to the custom event emitted by your storefront and extracts the relevant data to build the Relay instance. You need to manually emit the coveo_shopify_config event in your Hydrogen storefront, with the relevant data.

// front-end code example

window.Shopify.analytics.publish("coveo_shopify_config", {
  "accessToken": "<ACCESS_TOKEN>",
  "organizationId": "<ORGANIZATION_ID>",
  "trackingId": "<TRACKING_ID>",
  "clientId": "<CLIENT_ID>",
})

// getCoveoShopifyEvent.ts

import { ExtensionApi } from "@shopify/web-pixels-extension";
import { COVEO_SHOPIFY_CONFIG_KEY } from "@coveo/shopify/utilities"; 
import { createStorage } from "./storage"; 

export interface CoveoShopifyEvent { 
  accessToken: string;
  organizationId: string;
  trackingId: string;
  clientId: string;
}

export const registerCoveoShopifyEventListener = ({ analytics, browser }: ExtensionApi) => {
  const storage = createStorage(browser);

  let resolveCoveoShopifyEvent: (value: CoveoShopifyEvent) => void; 
  const coveoShopifyEventPromise = new Promise<CoveoShopifyEvent>((resolve) => {
    resolveCoveoShopifyEvent = resolve;
  });

  analytics.subscribe(COVEO_SHOPIFY_CONFIG_KEY, async (event) => { 
    const settings = event.customData as unknown as CoveoShopifyEvent; 
    if (validateCoveoShopifyEvent(settings)) { 
      resolveCoveoShopifyEvent(settings);
      await storage.set(COVEO_SHOPIFY_CONFIG_KEY, settings);
    }
  });

  const getCoveoShopifyEvent = async () => {
    const settings = await storage.get<CoveoShopifyEvent>(COVEO_SHOPIFY_CONFIG_KEY);
    if (validateCoveoShopifyEvent(settings)) { 
      return settings;
    }
    return coveoShopifyEventPromise; 
  };

  return { getCoveoShopifyEvent };
};

const validateCoveoShopifyEvent = (settings: unknown): settings is CoveoShopifyEvent => {
  const coveoShopifyEvent = settings as CoveoShopifyEvent;

  if (
    coveoShopifyEvent &&
    typeof coveoShopifyEvent === "object" &&
    typeof coveoShopifyEvent.organizationId === "string" &&
    coveoShopifyEvent?.organizationId?.length &&
    typeof coveoShopifyEvent.trackingId === "string" &&
    coveoShopifyEvent?.trackingId?.length &&
    typeof coveoShopifyEvent.accessToken === "string" &&
    coveoShopifyEvent?.accessToken?.length &&
    typeof coveoShopifyEvent.clientId === "string" &&
    coveoShopifyEvent?.clientId?.length
  ) {
    return true;
  } else {
    console.warn(`Received Coveo Shopify event with invalid settings: ${JSON.stringify(settings)}`);
    return false;
  }
};

	The @coveo/shopify package exports the `COVEO_SHOPIFY_CONFIG_KEY` constant, which is used to identify the custom event name emitted by the storefront.
	The `createStorage` helper function will be defined next.
	The interface for the custom event data that will be emitted by the storefront and used to create the Relay instance.
	A promise that will be resolved with the Coveo Shopify event data when the custom event is received.
	Subscribe to the custom event emitted by the storefront.
	The custom data of the event is expected to be of type `CoveoShopifyEvent`.
	Validate the custom data to ensure it contains the required properties. Then, resolve the promise with the settings and store them in the browser storage.
	If the settings are valid, return them.
	If the settings aren’t valid or not available, return the promise that will be resolved when the custom event is received. This allows the web pixel to wait for the custom event to be emitted by the storefront before proceeding with the Relay instance creation and event logging.

Create the helper storage file.

// src/storage.ts

import { ExtensionApi } from "@shopify/web-pixels-extension";

export const createStorage = (browser: ExtensionApi["browser"]) => ({
  get: async <T>(key: string) => {
    const value = (await browser.cookie.get(key)) || (await browser.localStorage.getItem(key));
    if (value) {
      try {
        return JSON.parse(value) as T;
      } catch {
        return;
      }
    }
  },
  set: async <T>(key: string, value: T) => { 
    const encodedValue = JSON.stringify(value);
    await browser.cookie.set(key, encodedValue);
    await browser.localStorage.setItem(key, encodedValue);
  },
});

Store the value in both the cookie and local storage to improve reliability.

Populate the index.ts file to register the web pixel extension.

// src/index.ts

import { createRelay } from "@coveo/relay";
import { ExtensionApi, register } from "@shopify/web-pixels-extension";

import { ecAddToCartEvent, ecProductViewEvent, ecPurchaseEvent, ecRemoveFromCartEvent } from "./ecEventBuilders.ts";
import { webPixelRelayEnvironment } from "./relayEnvironment";
import { name as webPixelPackageName, version as webPixelPackageVersion } from "../package.json";
import { registerCoveoShopifyEventListener, CoveoShopifyEvent } from "./getCoveoShopifyEvent.ts";

register((extensionAPI: ExtensionApi) => {
  const { analytics } = extensionAPI;
  const { getCoveoShopifyEvent } = registerCoveoShopifyEventListener(extensionAPI);

  const relayPromise = createRelayPromise(extensionAPI, getCoveoShopifyEvent);

  analytics.subscribe("checkout_completed", async (event) =>
    (await relayPromise).emit("ec.purchase", ecPurchaseEvent(event.data.checkout)),
  );
});

const createRelayPromise = async (
  extensionAPI: ExtensionApi,
  getCoveoShopifyEvent: () => Promise<CoveoShopifyEvent>,
) => {
  const { clientId, trackingId, accessToken } = await getCoveoShopifyEvent();
  const relay = createRelay({
    trackingId,
    token: accessToken,
    url: `https://${settings.organizationId}.analytics.org.coveo.com/rest/organizations/${settings.organizationId}/events/v1`, 
    environment: webPixelRelayEnvironment(extensionAPI, clientId),
    source: [`${webPixelPackageName}@${webPixelPackageVersion}`],
  });
  return relay;
};

Use the organization ID in the web pixel settings to configure the endpoint. It would also be possible to retrieve this ID from the custom event data.

When activating your web pixel, pass your Coveo organization ID in the organizationId setting.

mutation {
  webPixelCreate(webPixel: { settings: "{\"organizationId\":\"myshoprzh5nbge\"}" }) {
    userErrors {
      code
      field
      message
    }
    webPixel {
      settings
      id
    }
  }
}

Atomic

Atomic logs click events automatically.

We recommend creating an app web pixel with Coveo Relay to track cart, product, and purchase events, when the following events are logged from your store, respectively:

The following implementation example explains how to do so.