Commerce UA API reference

This is for:

Developer

Coveo UA command list

Commands Description Associated parameters

init

Initializes the Coveo Analytics JavaScript

<COVEO_API_KEY> <ENDPOINT>

set

Sets the website context or user ID

custom userId currencyCode

version

Returns the current version of the tracking library

ec:addProduct

Includes the relevant product data in the event you’re about to send

ec:setAction

Specifies the action done on this data

add remove detail impression purchase click

send

Sends an event with a given name and payload to the analytics endpoint

event pageview

Global fields reference

User fields reference

Users fields are related to the current user.

userId (string)

Example: myuser@mycompany.com

Important

Before using the userId field, see User Authentication.

currencyCode (string)

The currency code is a three-letter code that identifies the user’s currency.

The code follows the ISO 4217 standard.

Example: CAD

anonymizeIp (boolean)

Use this field to anonymize the IP address by removing the last subnet of the current user’s IP address. Coveo will never store unencrypted IPs, even when this setting is set to false.

loyaltyCardId (string)

A unique identifier provided to a returning user.

loyaltyTier (string)

A level of membership where users receive perks and benefits depending on their rank.

Example: Platinum

thirdPartyPersona (string)

This represents additional market segmentation based on user characteristics (demographics, interests, needs, or location) which aren’t created by Coveo Machine Learning (Coveo ML). When you already have a set of segments for your users, enter the information in this field.

companyName (string)

The name of a specific company for business-to-business sales.

favoriteStore (string)

The primary store selected by a returning user.

storeName (string)

The name of the current store selected by the user.

userIndustry (string)

For business-to-business (B2B) environments that need to indicate which industry’s vertical structure the user belongs to (e.g., healthcare,technology, insurance).

userRole (string)

For business-to-business (B2B) environments that need to indicate the role or title of the current user (e.g., director, manager, specialist).

userDepartment (string)

For business-to-business (B2B) environments that need to indicate the department of the current user (e.g., IT, Design, Procurement, Sales).

businessUnit (string) - deprecated

Important

This field has been deprecated. You no longer need to send this data when logging analytics events.

This field defines the current catalog in use. For a solution with multiple catalogs, we use the catalog passed in this field to separate reporting and machine learning between catalogs.

Page fields reference

Page fields are sent using the set command, or alongside a pageview event as shown in the following command:

coveoua('send', 'pageview', {
    page: '/mypage'
})

page (string)

The path portion of the page URL that allows users to track pages for single page apps (SPA) and mobile apps.

To send the page, add the following line before sending the pageview event, for example:

coveoua('set', 'page', window.location.pathname)

title (string)

The title of the page. The default value is retrieved from document.title.

Example: My Super Site

location (string)

The full URL of the page. The default value is retrieved from document.location.

Example: https://www.mysupersite.com/home

Global custom fields reference

The custom field allows users to add additional custom values as an object. Everything in this field will be unfolded to the parent object and then sent to coveoua.

To set custom fields for the whole page, use the set command, passing the custom string as a second argument, and an object containing the desired key-value pairs as a third argument.

Example

On custom user data

coveoua('set', 'custom',  {
  visitorAge: 18,
  rewardsMember: true
});
// sets the `custom` field for each top-level object

When you use the send command

coveoua('send', 'pageview');

The following data is sent to coveoua:

visitorAge: 18,
rewardsMember: true
Note

You can use a Coveo ML Content Recommendation (CR) model which leverages collect events to render content recommendations. In this case, all of the pageview events that are sent to Coveo Usage Analytics (Coveo UA) must contain a contentIdKey and contentIdValue, both of which are defined as custom fields. For instructions, see Send page view events when using collect events.

Product data fields reference

Product fields reference

Product fields are set with the ec:addProduct command.

id (string)

The SKU used to uniquely identify your product.

Example: 001-red

name (string)

Example: Very nice shoe

brand (string)

Example: Coveo

category (string)

Represents a grouping of products having particular shared characteristics.

Field format Examples

Single

"sport"

Hierarchical

"sport/hiking/apparel"

Multi-value

"sport/hiking/apparel|sport/climbing/apparel"
Note

The format expected when uploading category values to your index is | and ; for delimiting hierarchies and multiple values, respectively. Whereas the format expected when logging events is / and |, respectively.

Ensure that you aren’t sending events that include breadcrumbs with temporary categories or events, such as sales or clearance items.

group (string)

Represents an ID that’s specific to an item that has multiple SKUs attached to it. This is useful if you only want one item per group to be recommended by the machine learning algorithms.

Note

When you structure your items with product grouping, ensure you add the group field to the product dataset in all sent events.

Using the recommended approach for product data, you would find, for example, "ec_item_group_id": "001" and "productid": "001-red" in the product dataset payload. The group can be represented by any string as long as it’s consistent, in other words, the same value 001, is used on the different products in the group.

variant (string)

A string that defines the unique non-displayable version of the product. Often called a stock keeping unit (SKU).

Example: 001-red-8_wide

Note

If the variant field is sent on an initial event, you must ensure it’s sent on all future events, where applicable.

For example, when a user lands on a product detail page where a variant item is selected, send the variant in the detail event and ensure the variant is also sent if the user adds the item to their cart and completes a purchase. Conversely, when landing on a product detail page where a variant isn’t selected, suggests you don’t need to send a detail event with the variant.

price (Monetary values)

The price of the product. Price values are only meaningful if accompanied by a currencyCode.

Example: 12.34

quantity (numeric)

Quantity of the product bought.

Example: 12

coupon (string)

The name of the coupon used on this specific product.

Example: PROMO-1234

position (numeric) - deprecated

Important

This field has been deprecated. You no longer need to send this data when logging analytics events.

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

Example: 2

Note

For products, only a position greater than or equal to 1 is valid. If position: 0 is passed, it’ll be removed and not sent through the API with the item.

Transaction fields reference

Transaction fields are set with coveoua('ec:setAction', <ACTION>)

id (string)

An identifier used to track a specific transaction.

Example: transaction-1234

affiliation (string)

The store where a transaction took place. Sent when you want to link a purchase or refund to a specific store.

Example: Shoe Store

revenue (Monetary values)

The total value of the transaction, including taxes and shipping.

Example: 123.21

tax (Monetary values)

The total transaction tax.

Example: 8.23

shipping (Monetary values)

The transaction shipping cost.

Example: 5.00

coupon (string)

The name of the coupon used on the whole transaction.

Example: PROMO-FREE-SHIPPING-2020

Quote fields reference

Field references related to providing a quote to the user.

id (numeric)

An identifier used to track a specific transaction.

affiliation (string)

The store where a quote took place. Sent when you want to link a quote to a specific store.

Example: Shoe Store

Review fields reference

Review fields provide customers the opportunity to rate and comment on products they have purchased.

id (numeric)

An identifier used to track a specific transaction.

rating (numeric)

A rating described on a numeric scale from 0 to 10.

Note

When using a different rating method, for example a review of 0 to 5 stars, ensure you convert the score to a 0 to 10 scale.

comment (string)

A written summary of a user’s experience with a product or service.

Product data custom fields reference

The custom field allows users to add additional custom values as an object. Everything in this field will be unfolded to the parent object and then sent to coveoua.

To set custom fields in a product impression, use the ec:addProduct command, and add a custom object containing the desired key-value pairs in your main product impression object.

Example

On custom product data, when you use the ec:addProduct command

  coveoua('ec:addProduct', {
    'id': '001-red',
    'name': 'A very nice pair of shoes',
    'brand': 'Coveo',
    'category': 'Running shoes',
    'price': 90.22,
    'variant': '001-red-8_wide',
    'custom' : {
      'onSale' : false
    }
});

When you use the send command

coveoua('send', 'event');

It will send the following data

id: '001-red',
name: 'A very nice pair of shoes',
brand: 'Coveo',
category: 'Running shoes',
price: 90.22,
variant: '001-red-8_wide',
onSale : false

Product action type reference

Action Description

'click'

The user clicked on a product.

'detail'

The user accessed a detailed view of the product.

'quickview'

The user accessed a quick view of the product.

'add' or 'remove'

The user added or removed a product from their cart.

'purchase' or 'refund'

The sale or return of one or more products.

'bookmark_add' or 'bookmark_remove'

The user added or removed a product from their bookmark.

'compare_add' or 'compare_remove'

The user added a product to compare to another or removed one.

'review_add' or 'review_remove'

The user added or removed a review on a product.

'quote'

The user asked for a quote regarding a given product (e.g., asked for a price on a large quantity of products in return for a discount).

'checkout'

The user initiated the checkout process for one or more products.

'checkout_option'

The user selected an option value for a given checkout step (e.g., selecting payment options or shipping methods).

Monetary values

Currency is a specification of a monetary amount. The following table lists the acceptable currency data types.

Currency data type Examples

A positive or negative integer.

12, 22, 0 or -5

A positive or negative decimal value with up to 6 decimal places using . as a decimal separator. (Recommended)

1337.123456, -1.2 or .97

A string, which may contain a non-numeric prefix in front of an integer or decimal value. In this case, Coveo interprets the number by stripping away the prefix up to the first numeric, -, or . character.

Acceptable strings include "€20.78", "$-15.78", "ZWL100000000", but not "15.99EUR", "$2,275.00" or "(0.075)"
Note

Coveo doesn’t support numbers using different decimal separators other than .. Currency amounts passed in numbers with thousand separators, numbers in parentheses, or numbers in scientific notation formats will be ignored. Coveo also doesn’t interpret any currency symbols or currency codes in currency fields. If needed, the explicit currency code should be indicated in the currencyCode field.

Search hub

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

Depending on the type of interface from which the event originates, the value of the search hub must contain:

Type of interface Contains the string

A search page

search

A product listing page

listing
Note

For recommendation components, the attribution mechanism is automatically managed by tracking a unique ID throughout the actions leading to a product being added to a cart or purchased. Therefore, there’s no specific naming convention to use when choosing a search hub value for your recommendation component, but note that it’s a good practice to add recs in the component’s search hub value (e.g., home_page_recs).

However, the identifier value of the recommendation component is used for reporting purposes. Specifically, the Coveo UA service utilizes the recommendation parameter value from queries originating from a particular recommendation component to generate reports on the performance of that specific component.

To ensure clarity and easy recognition, we strongly recommend assigning a meaningful and recognizable value as the identifier for your recommendation component.

You can achieve this by setting the id property for your recommendation component. If you are using Headless, for instance, you can specify the component’s ID by utilizing the id property when initializing the RecommendationList controller.
Example

For page views:

  coveoua('send', 'pageview', {
  "searchHub": "<SEARCH_HUB>"
  });

For other events:

  coveoua('send', 'event', {
  "searchHub": "<SEARCH_HUB>"
  });

Where <SEARCH_HUB> is the name of your search hub (e.g., "storefront_search" for a search page or "MyBrand_listing" for a product listing page).

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

Important

Coveo ML models use the searchHub value as a default filter field. These filters don’t affect how the 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).