Measure Events on a Listing or Search Page
Measure Events on a Listing or Search Page
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.

Tracking Commerce Events Prerequisites
-
Sent the page view (if necessary) before you add product data, set the actions, and dispatch the event
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.

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:
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 thesearchUid
, 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 |
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');
If | Then |
---|---|
The |
There’s no need to send the |
The user interaction didn’t open a new page |
Manually send the |
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.

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 |
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 thesearchUid
, 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 |
There’s no need to send the |
The user interaction didn’t open a new page |
Manually send the |
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 |
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 thesearchUid
, 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 |
There’s no need to send the |
The user interaction didn’t open a new page |
Manually send the |
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 |
|
For a recommendation component |
|
For product listings |
|
|
Coveo ML models use the |
{
...
"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 |
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