Log usage analytics events
Log usage analytics events
This section provides guidelines for performing HTTP requests against the Coveo Usage Analytics (Coveo UA) Write API to log different types of events.
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.
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:
Log events asynchronously.
Don’t make end users wait for UA Write API responses.
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 (e.g., identifying content gaps or improving case deflections). Some tests could be required to ensure that the proper data is passed to Coveo UA.
For additional guidance, we recommend exploring the following courses on Coveo Level Up:
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:
When logging search and click events, grouping agents allows the Coveo ML service to learn from said groups (see Search event
customDataand Click event
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
customDataproperty of your request body, key-value pairs such as:
<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.
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.
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>
<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 (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.
It identifies a user on a browser for a specific website 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
visitor} (string) query parameter is the never expiring unique identifier of the visitor.
It has a maximum length of 128 ASCII characters, and the best practice is to use a v4 UUID, as in the following example:
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.
Record this newly generated identifier and use it in future requests.
It should be included in the cookie, but also as the
prioritizeVisitorParameter (Boolean) query parameter is explicitly set to
visitor query parameter is overridden by the
visitor cookie whenever it’s present.
Sometimes, you may want to force the UA Write service to use the
visitor query parameter rather than the
If that’s the case, set the
prioritizeVisitorParameter query parameter to
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
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} is a GUID similar to the following:
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.
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.
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.
visitorparameter exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts.