Tracking Commerce Events

The coveo.analytics.js script is used to send events to the Coveo Usage Analytics service.

How the Script Is Used

The library accepts a format similar to the Google Analytics tag (also called the analytics.js library).

The first parameter is always a command name, and the other parameters vary depending on the command executed.

The command init is used to initialize the script and must be called once in each page. I.e., coveoua('init', <COVEO_API_KEY>);

Some commands allow setting data. For example, the set command allows setting a parameter for the whole page. Ex: coveoua('set', 'currencyCode', 'EUR');

The most important command is send, since it gets cumulated data and sends the event to the Coveo Usage Analytics service. E.g., coveoua('send', 'pageview');

Initializing the Script

You must include the following script tag to load the coveo.analytics library into your page.

<script>
(function(c,o,v,e,O,u,a){
a='coveoua';c[a]=c[a]||function(){(c[a].q=c[a].q|| []).push(arguments)};
c[a].t=Date.now();u=o.createElement(v);u.async=1;u.src=e;
O=o.getElementsByTagName(v)[0];O.parentNode.insertBefore(u,O)
})(window,document,'script','https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js')
coveoua('init', <COVEO_API_KEY>);
</script>

The COVEO_API_KEY parameter must be replaced with an API Key with the Push access level on the Analytics Data domain.

Sending a Page View

To send a page view event, you can use the following command:

coveoua('send', 'pageview', <PAGE>, <FIELDS_OBJECT>);

Where:

<PAGE> (string, optional) should be set when the end user navigates to a new page in a Single Page Application (SPA).

<FIELDS> (object, optional) contains additional metadata to send along with the event (see Fields Reference).

Examples

The following command allows you to include the path of the current visited page.

coveoua('send', 'pageview');

For Single-Page Applications (SPA), you can add the page parameter to notify when the user navigates to a new page, as seen in the following command:

coveoua('send', 'pageview', '/mycurrentpage');

Sending a Generic Event

To send any type of event, you can use the following command:

coveoua('send', 'event', <EVENT_CATEGORY>, <EVENT_ACTION>, <EVENT_LABEL>, <EVENT_VALUE>, <FIELDS_OBJECT>);

Examples

The following command allows you to send an event that tracks a click on a Ad from the current campaign.

coveoua('send', 'event', 'Ad', 'click', 'Black Shoes 2020 Campaign');

Measuring a Product Details View

To measure a product details view, you can use the following commands:

// Adds a product to the data to send.
coveoua('ec:addProduct', {
    'id': 'sku-1234',
    'name': 'A very nice pair of shoes',
    'brand': 'Nice',
    'category': 'Running shoes',
    'price': 90.22,
    'variant': 'sku-1234-black',
    'position': 1
});
// Defines the action done on the data.
coveoua('ec:setAction', 'detail');

In this example, the user has viewed the details of the product. However, data has only been set by the previous commands. It has to be sent with either a pageview or with a generic event:

coveoua('send', 'pageview');

Measuring an Addition to the Cart

// Adds a product to the data to send.
coveoua('ec:addProduct', {
    'id': 'sku-1234',
    'name': 'A very nice pair of shoes',
    'brand': 'Nice',
    'category': 'Running shoes',
    'variant': 'sku-1234-black',
    'price': 90.22,
    'quantity': 1
});
// Defines the action done on the data.
coveoua('ec:setAction', 'add');

In this example, the user has added a product to the cart. Since the page is already loaded and the page view event logged, the data must be sent on a generic event:

coveoua('send', 'event', 'Conversion', 'Cart', 'Add to Cart', 'sku-1234');

Measuring a Removal from the Cart

// Adds a product to the data to send.
coveoua('ec:addProduct', {
    'id': 'sku-1234',
    'name': 'A very nice pair of shoes',
    'brand': 'Nice',
    'category': 'Running shoes',
    'variant': 'sku-1234-black',
    'price': 90.22,
    'quantity': 1
});
// Defines the action done on the data.
coveoua('ec:setAction', 'remove');

In this example, the user has removed a product from the cart. Since the page is already loaded and the page view event logged, the data must be sent on a generic event:

coveoua('send', 'event', 'conversion', 'Cart', 'Remove from Cart', 'sku-1234');

Measuring Purchases

To send a purchase event, you must add data to your event and set the action to purchase like so:

coveoua('ec:addProduct', {
    'id': 'sku-1234',
    'name': 'A very nice pair of shoes',
    'category': 'Running shoes',
    'brand': 'Nice',
    'variant': 'sku-1234-black',
    'price': 22.99,
    'quantity': 1
});
// Defines the action done on the data.
coveoua('ec:setAction', 'purchase', {
    'id': 'transaction-1234',
    'affiliation': 'My Shoe Store',
    'revenue': '12.34',
    'tax': '1.85',
    'shipping': '5.00',
    'coupon': 'PROMO-1234',
});
// Send the event on a page view or a generic event.
coveoua('send', 'pageview');

Possible Actions

The coveoua('ec:setAction', <ACTION>) command allows you to set the executed action on your data.

Click (click)

The product has been clicked by the user.

Click events are dispatched using coveoua("send", "event", <EVENT_CATEGORY>, <EVENT_ACTION>);

Detail (detail)

The user has accessed a detailed view of the product.

Detail events are dispatched using coveoua("send", "pageview");

Quick View (quickview)

The user has accessed a quick view of the product.

Detail events are usually dispatched using coveoua("send", "event", <EVENT_CATEGORY>, <EVENT_ACTION>).

Added to Cart (add)

The user has added the product to their cart.

Click events are dispatched using coveoua("send", "event", <EVENT_CATEGORY>, <EVENT_ACTION>);

Removed from Cart (remove)

The user has removed the product from their cart.

Click events are dispatched using coveoua("send", "event", <EVENT_CATEGORY>, <EVENT_ACTION>);

Fields Reference

User Fields

Users fields are related to the current user.

They can be set with coveoua("set", <FIELD_NAME>, <FIELD_VALUE>)

userId (String)

Example: myuser@mycompany.com

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

Product Fields

Product fields are set with the ec:addProduct command.

id (String, Required)

The SKU used to uniquely identify your product.

Example: NiceShoe-1234

name (String)

(Optional)

Example: Very nice shoe

brand (String)

(Optional)

Example: Nice

category (String)

(Optional)

Example: Shoe

variant (String)

(Optional)

A string that defines the variant of the product.

Example: Black

price (Numeric)

(Optional)

Example: 12.34

quantity (Numeric)

(Optional)

Example: 12

coupon (String)

(Optional)

The name of the coupon used on this specific product.

Example: PROMO-1234

position (Numeric)

(Optional)

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

Example: 2

Transaction Fields

id (String)

(Optional)

An identifier used to track a specific transaction.

Example: transaction-1234

affiliation (String)

(Optional)

Example: Shoe Store

revenue (Numeric)

(Optional)

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

Example: 123.21

tax (Numeric)

(Optional)

The total transaction tax.

Example: 8.23

shipping (Numeric)

(Optional)

The transaction shipping cost.

Example: 5.00

coupon (String)

(Optional)

The name of the coupon used on the whole transaction.

Example: PROMO-FREE-SHIPPING-2020

Page Fields

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

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

page (String)

The path portion of the page URL.

Example: /mycurrentpage

title (String)

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

Example: My Super Site

location (String)

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

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

Event Fields

Event fields are sent using the send action or alongside a event event like the following command:

coveoua('send', 'event', {
    eventCategory: 'Ad',
    eventAction: 'click',
    eventLabel: 'My Super Campaign',
    eventValue: '10'
})

eventCategory (String, Required)

The name of the group for objects that you want to analyse together.

eventAction (String, Required)

The name of the action that was executed.

eventLabel (String)

(Optional)

Additional information that you want to pass to further segment your objects.

eventValue (String)

(Optional)

A numerical value associated with the event.