Measure Events on a Listing or Search Page

Ecommerce Developer Product Documentation

The following image is taken from a Coveo-powered product listing page view of the fictitious online store TheGym. It contains elements that can trigger usage analytic events, such as how to Measure Impression Data on a Listing Page and how to Measure Product Clicks on a Search-driven Listing Page. The examples below also apply to search pages and will depend on your specific use case.

TheGym Listing Page View

Tracking Commerce Events Prerequisites

Before each event, ensure that you’ve:

Measure Impression Data on a Listing Page

The product listing (or search) page contains at least one main product impression, which is the main list of results that you see.

TheGym Listing Impression Data View

When the product listing (or search) page is powered by Coveo, the Coveo Search API logs impressions automatically to Coveo Analytics. However, there are some scenarios where manually logging impressions is required or recommended:

  • When the list is powered by Coveo, and you have a proxy (or equivalent process) that adds client-side data to product data.

  • When the list isn’t powered by Coveo, and you would like to compare impressions with and without Coveo.

To send an impression manually, use the following command:

coveoua('ec:addImpression', <DATA>)

Where you replace <DATA> with the product impression object containing the relevant fields. For reference information, see Impression Data Field Reference.

// Add the relevant product data.
coveoua('ec:addImpression', {
  'id': '037212201_DKBL',
  'name': 'backland 120',
  'brand': 'Atomic',
  'category': 'sport/ski_mountaineering/boots',
  'price': 447.20,
  'variant': '037212201_DKBL_22',
  'list': `<LIST_VALUE>`,
  'position': 1
});

coveoua('ec:addImpression', {
  'id': '036834601_WHBK',
  'name': 'mtn explore 100',
  'brand': 'salomon',
  'category': 'sport/ski_mountaineering/boots',
  'price': 429.95,
  'variant': '036834601_WHBK_22',
  'list': `<LIST_VALUE>`,
  'position': 2
});

coveoua('ec:addImpression', {
  'id': '035141901_WHT',
  'name': 'S1 carbon',
  'brand': 'scott',
  'category': 'sport/ski_mountaineering/boots',
  'price': 553.68,
  'variant': '035141901_WHT_22',
  'list': `<LIST_VALUE>`,
  'custom' : {
      'onSale' : true
    },
  'position': 3
});

//...

Where you would replace <LIST_VALUE> by one of the following:

  • If your product listing (or search) page is powered by Coveo, use coveo:search:${searchUid} (e.g, coveo:search:9f5da2cc-11ad-11ec-82a8-0242ac130003). For information on how to retrieve the searchUid, see Extract the SearchUid.

  • If your product listing (or search) page isn’t powered by Coveo, enter the name of your list (e.g., ski boot listing).

Note

When you structure your items with product grouping, ensure you add the group field to the product dataset. This will send all related items in the analytics payload.

Then, use the ec:setAction command to specify that the action done on this data is to send the impression data:

coveoua('ec:setAction', 'impression');

Finally, use the send command to send the event to Coveo UA:

If Then

The impression view action and product information is added before the pageview event is sent

There’s no need to send the pageview event. The pageview event you previously configured on the page will contain the action and product information.

The user interaction didn’t open a new page

Manually send the impression view action with a generic event.

Measure Product Clicks on a Search-driven Listing Page

On a search-driven Product Listing Page powered by the Coveo JavaScript Search Framework, you want to measure a product click event. In the image below, a user has searched for shoes and clicked on a product in the results list of fictitious online store, TheGym.

TheGym Product Click Search Page View

First, use the ec:addProduct command to include the relevant product data in the event you’re about to send:

// add the relevant product data.
coveoua('ec:addProduct', {
  'id': '038327301_1400',
  'name': 'xa pro 3d gore-tex',
  'brand': 'salomon',
  'category': 'sport/hiking/shoes/trail running',
  'price': 112.00,
  'quantity': 1,
  'position': 3
});
Note

When you structure your items with product grouping, ensure you add the group field to the product dataset. This will send all related items in the analytics payload.

Then, use the ec:setAction command to specify that the action done on this data is a product click:

// ...
coveoua('ec:setAction', 'click', {
  list: `<LIST_VALUE>`
});

Where you would replace <LIST_VALUE> by one of the following:

  • If your product listing (or search) page is powered by Coveo, use coveo:search:${searchUid} (e.g, coveo:search:9f5da2cc-11ad-11ec-82a8-0242ac130003). For information on how to retrieve the searchUid, see Extract the SearchUid.

  • If your product listing (or search) page isn’t powered by Coveo, enter the name of your list (e.g., running shoe listing).

Finally, use the send command to send the event to Coveo UA:

If Then

The click action and product information is added before the pageview event is sent

There’s no need to send the pageview event. The pageview event you previously configured on the page will contain the action and product information.

The user interaction didn’t open a new page

Manually send the click action with a generic event.

Measure Add to Cart From a Search Results Page

On a search results page powered by the Coveo JavaScript Search Framework or by an alternate search engine, you want to measure an Add to Cart event. This type of event differs slightly from the Add to Cart event triggered on a Product detail page, where a user may add the product directly to their shopping cart, bypassing the product detail page.

First, use the ec:addProduct command to include the relevant product data in the event you’re about to send:

// add the relevant product data.
coveoua('ec:addProduct', {
  'id': '038327301_1400',
  'name': 'xa pro 3d gore-tex',
  'brand': 'salomon',
  'category': 'sport/hiking/shoes/trail running',
  'price': 112.00,
  'quantity': 1,
  'position': 3
});
Note

When you structure your items with product grouping, ensure you add the group field to the product dataset. This will send all related items in the analytics payload.

Then, use the ec:setAction command to specify that the action done on this data is a product add:

// ...
coveoua('ec:setAction', 'add', {
  list: `<LIST_VALUE>`
});

Where you would replace <LIST_VALUE> by one of the following:

  • If your product listing (or search) page is powered by Coveo, use coveo:search:${searchUid} (e.g., coveo:search:9f5da2cc-11ad-11ec-82a8-0242ac130003). For information on how to retrieve the searchUid, see Extract the SearchUid.

  • If your product listing (or search) page isn’t powered by Coveo, enter the name of your list (e.g., trail running shoe).

Finally, use the send command to send the event to Coveo UA:

If Then

The click action and product information are added before the pageview event is sent

There’s no need to send the pageview event. The pageview event you previously configured on the page will contain the action and product information.

The user interaction didn’t open a new page

Manually send the click action with a generic event.

Impression Data Field Reference

originLevel1 (String, Required)

The name/identifier of the search interface from which a given UA event originates.

If originLevel1 isn’t specified and the request is authenticated with a search token, the service attempts to extract the searchHub value from the access token that authenticated the log search event request (see Set the Search Hub).

When you pass the originLevel1 field, you must name the origin of your search page as follows, in order to properly calculate attribution in commerce dashboards.

Type Field value must contain

For a search page

Search

For a recommendation component

Recommendations or Recs

For product listings

ProductListing or Listing
Important

Coveo ML models use the originLevel1 value as a default filter field. Filters don’t affect how Coveo ML models learn, but they must be logged correctly for recommendations to work. When Coveo ML models make suggestions, items which don’t meet the right filters are ignored (see Getting Query Suggestions - Troubleshooting).
EXAMPLE
{
  ...
  "originLevel1": "<CONTENT_CONTEXT>_Search",
  ...
}

Product fields are set with the ec:addImpression command.

id (String, Required)

The SKU used to uniquely identify your product.

Example: 001-red

position (Numeric, Required)

The item’s position. For example, the first displayed in a list should have position: 1.

Example: 2

Note

For products and impressions, only a position greater than or equal to 1 is valid. If position: 0 is passed, it’ll be removed from the payload.

name (String, Optional)

Example: Very nice shoe

brand (String, Optional)

Example: Coveo

category (String, Optional)

Example: Shoe

variant (String, Optional)

A string that defines the variant of the product.

Example: 001-red-8_wide

list (String, Optional)

The list that the associated products belong to. For an example of this parameter, see Measure Events on a Listing or Search Page.

price (Currency, Optional)

Example: 12.34

What's next for me?