Capture cart events

This is for:

Developer

In this article

When to capture a cart event
How to capture a cart event
Validating the cart event

The Event Protocol and Relay library are currently in early access. If you’re interested in using the Event Protocol and Relay library, reach out to your Customer Success Manager (CSM).

This article explains how to capture cart events and send the information to Coveo Usage Analytics (Coveo UA).

When to capture a cart event

Anytime the content of a cart is modified by a user, the interface must log a cart event, together with the product information payload. Cart content modifications may include the addition or removal of products, or changes in quantity of existing products in the cart. Depending on your site’s design, cart events can be triggered from different pages, such as:

From a page which shows the current content of a visitor's shopping cart
From an individual Product detail page
From a search results page
From a listing page
From a recommendations component

You must send an additional click event if the cart is directly modified from the search results page, listings page or recommendations component.

The following image is from the cart page view of the online sporting goods store Barca Sports, which provides visitors with the ability to modify the contents of their cart by increasing or decreasing the quantity of items. Minimally, you would want to log product information and the quantity added or removed in the product data payload. Coveo calculates quantity as the increase or decrease in value, and not the new total amount. For example, if a client changes the quantity of the item in cart from 1 to 2, the quantity to pass in the cart event is 1.

How to capture a cart event

Capturing a cart event depends on your implementation approach.

If you’re using Headless, capture the event using the Headless controllers.
If you’re not using Headless, use the Relay library directly to capture the event.

Capture a cart event using Headless

With the Headless library, you can capture cart events using the Cart controller.

For more details, see Managing the cart.

Capture a cart event using Relay

If you’re using Relay library, when a user adds a product to cart, you can run the following code to capture the event and send the information to Coveo.

const relay = createRelay({...}); 
relay.emit('ec.cartAction', { 
    action: 'add', 
    currency: 'USD',
    quantity: 1,
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});

	Initialize a Relay instance.
	Use the `emit` function to send an event with Relay, specifying the event name. In this example, the value is `ec.cartAction` since it’s capturing a cart event.
	Include the necessary event data, as outlined in the reference documentation. Here a single product is being added to the cart.

For a detailed description of the functions offered by the library, see the Relay documentation.

Note

When sending events with Relay, you don’t need to include the meta object mentioned in the Event Protocol Reference documentation, as it’s automatically added by the library.

Sending an additional click event

When managing cart modification events, with Coveo-powered components, adding products to the cart directly from search results, product listings, or recommendation carousels requires sending two events:

Click event
Cart event

const relay = createRelay({...});
relay.emit('ec.productClick', { 
    currency: 'USD',
    position: 1,
    responseId: '35009a79-1a05-49d7-b876-2b884d0f825b',
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});
relay.emit('ec.cartAction', { 
    action: 'add',
    currency: 'USD',
    quantity: 1,
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});

	Log the click event, following the reference documentation.
	Log the cart event, following the reference documentation.

Validating the cart event

It’s important to verify that your event is valid and contains the correct payload. Relay seamlessly integrates with Coveo Explorer, which can be used for event validation.

For more details on using Coveo Explorer to validate events, see Validating events.