Log usage analytics events

This is for:

Developer

This section provides guidelines for performing HTTP requests against the Coveo Usage Analytics (Coveo UA) Write API to log different types of events.

The Coveo search UI libraries (Atomic, Headless, and the JavaScript Search Framework) can automatically log search, click, and custom events. The Coveo UA library handles HTTP requests for logging view and generic collect events. We strongly recommend that you leverage these tools to build your Coveo-powered search interface.

However, you may have a legitimate reason for not using the Coveo UI or analytics libraries in your search integration. In this case, you must ensure that your custom implementation logs user interactions with your search interface in the same way that it would if you were relying on the Coveo libraries.

Generic guidelines

The following guidelines apply when logging any type of event through the UA Write API.

  • Follow all of the recommended standard practices when logging events, respecting the syntax and the nomenclature.

    The following services may not work correctly if you don’t use the standard names and values:

    Additionally, if you use both a search interface powered by the JavaScript Search Framework and a custom search interface with custom names in your organization, your usage analytics data will be heterogeneous. You and your Coveo Customer Success manager will struggle to make sense of it.

  • Log events asynchronously.

    Don’t make end users wait for UA Write API responses.

  • Don’t log events when end users reject cookies.

    You must implement a mechanism to prevent logging events when end users reject cookies. Not doing so pollutes your usage analytics data and affects data health.

  • Ensure that the information passed to Coveo UA fits your needs.

    The data that you pass should reflect the information that you want to track over usage analytics and how you want to track it. This information is typically related to monitoring usage or seeking improvements (for example, identifying content gaps or improving case deflections). Some tests could be required to ensure that the proper data is passed to Coveo UA.

    Tip

    For additional guidance, we recommend exploring the following courses on Coveo Level Up:

Examples

  1. You have many agents using an application.

    Perhaps you would like to pass information about the role, department, and level of agent to categorize or group them. As much as possible, such groupings should be made when logging events (using customData) rather than when reporting (using filters). There are two main reasons for this:

    1. When logging search and click events, grouping agents allows the Coveo ML service to learn from said groups (see Search event customData and Click event customData).

    2. At report time, having existing groups is a lot more efficient. Adding large numbers of filters to group agents is inefficient, both when designing dashboards and when the UA Read service feeds those dashboards.

    When logging usage analytics events, you would therefore include, in the customData property of your request body, key-value pairs such as:

    • "context_role": "<CONTEXT_ROLE>"

    • "context_department": "<CONTEXT_DEPARTMENT">

    • "context_level": "<CONTEXT_LEVEL">

    where:

    • <CONTEXT_ROLE> is the role of the agent sending the request.

    • <CONTEXT_DEPARTMENT> is the department of the agent sending the request.

    • <CONTEXT_LEVEL> is the level of the agent sending the request.

  2. You’re doing application support, where the target is to maximize the case deflection and minimize the case creation.

    In this situation, it’s important to track the case creation event, case cancellation, and other events related to the case itself, since it will help in determining the number of created and deflected cases (implicitly or explicitly, when there’s a cancel case event). The same applies for commerce, where adding items to carts, dropping carts, etc. could be important events to track.

Authentication

The UA Write API relies on the bearer HTTP authentication scheme. All HTTP requests made to log usage analytics events must include an Authorization header with a valid access token such as an API key or a search token (see Choose and implement a search authentication method):

Authorization: Bearer <token>

The <token> must grant the Analytics - Analytics data - Push privilege in the target Coveo organization.

Tracking sessions and visitors

It’s useful to track individual visitors and their activities for both usage analytics reporting and Coveo ML.

clientId

The clientId (string) body parameter is a v4 UUID that uniquely identifies a user on a browser. If you want to use this parameter, you need to generate its value yourself.

489aa3e3-aed2-4563-8e81-62bb73178a56

It identifies a user on a browser for a specific site and takes precedence over visitor when both parameters are present. Therefore when the clientId is present, the UA Write service won’t return a cookie containing the visitorID value.

visitor

The {visitor} (string) query parameter is the never expiring unique identifier of the visitor. It has a maximum length of 128 ASCII characters,[1] and the best practice is to use a v4 UUID, as in the following example:

28s6g49d-f81s-1435-2r5x153dle72

If no visitor value is provided, a new identifier is created and returned both as an HTTP visitor cookie and as the visitorId property in the query response.

Tip
Leading practice

Record this newly generated identifier and use it in future requests. It should be included in the cookie, but also as the visitor parameter, in case the user browser doesn’t support third-party cookies.

Unless the prioritizeVisitorParameter (Boolean) query parameter is explicitly set to true, the visitor query parameter is overridden by the visitor cookie whenever it’s present.

Note

If a clientId is also present, it takes precedence over the visitor, and therefore no tracking cookie is set.

Sometimes, you may want to force the UA Write service to use the visitor query parameter rather than the visitor cookie. If that’s the case, set the prioritizeVisitorParameter query parameter to true.

Example

You have several applications integrated with Coveo, and you want to track users across these applications to benefit from meaningful reporting and ML.

Instead of letting the UA Write service handle the visitor values for you, which would generate as many visitor values per end user as you have applications, you generate one visitor per end user, and you force the service to use it by passing it as visitor query parameter value, and by setting prioritizeVisitorParameter to true.

The Coveo ML Automatic Relevance Tuning (ART), Query Suggestion (QS), and Content Recommendation (CR) models use the visitor value to personalize learning for the user.

visitId

The {visitid} is a GUID similar to the following:

53s7v53d-h32r-1745-3d4f183ldi84

It tracks users' individual visits and expires after 30 minutes of inactivity. This value is handled entirely server-side by Coveo UA, and you can’t generate it manually.

The Coveo ML ART, QS, and CR models use the visitId to track sequences of events and learn from them.

Example

A request URL and header to log a custom event, where an API key with Analytics - Analytics data - Push privileges is provided in the header, and the visitor query parameter is passed in the URL. The org parameter doesn’t need to be included, since the organization will be retrieved from the API key.

POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/custom?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72

In this, the visitor cookie is automatically added by the browser.

What’s next?

Log search events

Log click events

Log custom events

Log view events

Log collect events

1. If the visitor parameter exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts.