--- title: Log usage analytics events slug: '1373' canonical_url: https://docs.coveo.com/en/1373/ collection: build-a-search-ui source_format: adoc --- # Log usage analytics events > **Important** > > We strongly recommend that all new Commerce implementations use the [Event Protocol](https://docs.coveo.com/en/o1n91230/) to log events. > The [Event Protocol](https://docs.coveo.com/en/o9je0592/) and [Coveo Relay library](https://docs.coveo.com/en/o9je0322/) are generally available for Commerce. > > However, they're in closed beta for Coveo for Service, Website, and Workplace implementations. > If you're interested in using the Event Protocol and Relay library for these implementations, contact your customer success manager (CSM). This section provides guidelines for performing HTTP requests against the [Usage Analytics Write API](https://docs.coveo.com/en/18/) to log different types of [events](https://docs.coveo.com/en/260/). The Coveo search UI libraries ([Atomic](https://docs.coveo.com/en/lcdf0264/), [Headless](https://docs.coveo.com/en/lcdf0493/), and the [JavaScript Search Framework](https://docs.coveo.com/en/187/)) can automatically log search, click, and custom events. The [Coveo UA library](https://docs.coveo.com/en/1818/) handles HTTP requests for logging [view](https://docs.coveo.com/en/2651/) and generic [collect](https://docs.coveo.com/en/l41i0031/) events. Leverage these tools to build your Coveo-powered [search interface](https://docs.coveo.com/en/2741/). 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: -- ** Standard [Coveo Analytics reports](https://docs.coveo.com/en/266/) ** [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) -- * 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](https://docs.coveo.com/en/m44f6381/). * Ensure that the information passed to Coveo Analytics fits your needs. The data that you pass should reflect the information that you want to track with 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 Analytics. ## Examples . 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 `customData`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs) and [Click event `customData`](https://docs.coveo.com/en/2064#click-event-customdata-key-value-pairs)). .. 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 Coveo Analytics events, you would therefore include, in the `customData` property of your request body, key-value pairs such as: -- ** `"context_role": ""` ** `"context_department": "` ** `"context_level": "` -- where: ** `` is the role of the agent sending the request. ** `` is the department of the agent sending the request. ** `` 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. ## Authentication The UA Write API relies on the bearer HTTP authentication scheme. All HTTP requests made to log events must include an `Authorization` header with a valid access token such as an API key or a [search token](https://docs.coveo.com/en/1346/) (see [Choose and implement a search authentication method](https://docs.coveo.com/en/1369/)): `Authorization: Bearer ` The `` must grant the **Analytics - Analytics data - Push** [privilege](https://docs.coveo.com/en/228/) in the target [Coveo organization](https://docs.coveo.com/en/185/). ## Tracking sessions and visitors It's useful to track individual visitors and their activities for both analytics reporting and Coveo ML. ### `clientId` The `{clientId}` (string) body parameter is a [v4 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) that uniquely identifies a specific browser and device combination. To use this parameter, generate its value yourself. ```text 489aa3e3-aed2-4563-8e81-62bb73178a56 ``` If you don't provide a `clientId` value when logging an event, Coveo Analytics generates one for you and returns it in the response. ### `visitor` (deprecated) The `[visitor](https://docs.coveo.com/en/nbub9475/)` (string) query parameter is the never-expiring unique identifier of the visitor. It has a maximum length of 128 ASCII characters, (If the `visitor` parameter exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts.) and the best practice is to use a [v4 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), as in the following example: ```text 28s6g49d-f81s-1435-2r5x153dle72 ``` > **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)](https://docs.coveo.com/en/1013/), [Query Suggestion (QS)](https://docs.coveo.com/en/1015/), and [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) models use the `visitor` value to personalize learning for the user. ### `visitId` The `{visitId}` is a GUID similar to the following: ```text 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. ```http 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](https://docs.coveo.com/en/1502/) [Log click events](https://docs.coveo.com/en/2064/) [Log custom events](https://docs.coveo.com/en/2650/) [Log view events](https://docs.coveo.com/en/2651/) [Log collect events](https://docs.coveo.com/en/l41i0031/)