Log Usage Analytics Events
coveoua script does).
The convention is to use
POST methods to send data to a server and
GET methods to retrieve data from a server. Although it’s still possible to log UA events using the
GET endpoints, these methods have now been deprecated and will stop working entirely in November 2021.
In the HIPAA environment, you can only use the
POST endpoints to log UA events.
The following guidelines apply when logging any type of event through the Usage Analytics Write API.
Follow all recommended standard practices when logging usage analytics events, respecting the syntax and the nomenclature.
Using custom names will require significant customization down the road because standard names and values are used by:
These services might therefore not work correctly when names are changed.
Log usage analytics events asynchronously.
Don’t make end users wait for Usage Analytics Write API responses.
The passed data should reflect the information you want to track over usage analytics and how you want to track it. The information you want to track is typically related to usage monitoring or improvement seeking (e.g., identify content gaps, improve case deflections). Some tests could be required to ensure that the proper data is passed down.
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:
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 Usage Analytics 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 such case, 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 item to carts, dropping carts, etc. could be important events to track.
The Usage Analytics 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 Choosing and Implementing a Search Authentication Method):
Authorization: Bearer <token>
If a Usage Analytics Write API request is authenticated using an
OAuth2 token, the search interface needs to specify a value for the
org query parameter, as
OAuth2 tokens are platform-wide and can therefore allow access to more than one Coveo organization. Otherwise, the
org value is extracted from the search token.
org (string); the name of the organization.
myorg - myorg6j53h4
Tracking Sessions and Visitors
For both usage analytics reporting and Coveo ML, it’s useful to track individual visitors and their activities.
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. If the
visitor value exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts. 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.
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.
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 Usage Analytics Write service to use the
visitor query parameter rather than the
visitor cookie. If that’s the case, set the
prioritizeVisitorParameter query parameter to
You have several applications integrated with Coveo Cloud, and you want to track end users across those applications in order to benefit from meaningful reporting and ML.
Instead of letting the Usage Analytics 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 visitId tracks individual visits of users and expires after 30 minutes of inactivity.
visitId is entirely handled server-side by Coveo UA, you can’t generate it.
The Coveo ML ART, QS, and ER models use the
visitId value to track sequences of events and learn from them.
visitIdvalue is a GUID similar to the following:
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
visitorquery parameter is passed in the URL. The
orgparameter need not be included since the organization will be retrieved from the API key.
POST https://analytics.cloud.coveo.com/rest/ua/v15/custom?visitor=28s6g49d-f81s-1435-2r5x153dle72 Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72
In such a case, the
visitor Cookie is automatically added by the browser.