--- title: Usage analytics slug: '365' canonical_url: https://docs.coveo.com/en/365/ collection: javascript-search-framework source_format: adoc --- # Usage analytics The [`Analytics`](https://coveo.github.io/search-ui/components/analytics.html) component is responsible for automatically sending HTTP requests to the Usage Analytics Write API to record events that represent [standard user interactions](https://docs.coveo.com/en/1389/) with a [search interface](https://docs.coveo.com/en/2741/). In addition, including this component in your search interface lets you [send your own UA events](#send-your-own-ua-events). ```html ``` Administrators can leverage recorded UA data to evaluate how users are interacting with a search interface, identify content gaps, and improve relevancy by generating and examining [dashboards](https://docs.coveo.com/en/256/) and [reports](https://docs.coveo.com/en/266/) within the [Coveo Administration Console](https://docs.coveo.com/en/183/) (see [Coveo Usage Analytics overview](https://docs.coveo.com/en/l3bf0598/)). Moreover, [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) features require UA data to function. ## Set the search hub The _search hub_ (or [origin level 1](https://docs.coveo.com/en/1337/)) identifies the search interface from which Search API and UA Write API requests are being sent. This information is vital for query pipeline routing, UA reporting, and enabling Coveo ML features in an implementation. Depending on which authentication method you're using in your search interface, you will normally enforce the search hub in the [search token](https://docs.coveo.com/en/56/) or in the [API key](https://docs.coveo.com/en/105/). In addition, when your search interface includes an `Analytics` component, you **must** set its [`searchHub`](https://coveo.github.io/search-ui/components/analytics.html#options.searchhub) option to the same search hub value that's enforced in the search token or API key. Otherwise, all UA Write API requests from that search interface will fail with 400 errors (that is, no UA events will be logged for that interface). For example, if you're using API key authentication in a search interface, and your API key is enforcing the `Community` search hub as a constraint, configure the `Analytics` component as follows: ```html ``` > **Note** > > In a standalone search interface that doesn't include an `Analytics` component (for example, global search box), enforcing the search hub in the search token or API key is sufficient. ## Send your own UA events In addition to the standard UA events that are automatically logged by the `Analytics` component, you may want to send your own UA events to track specific user interactions in your search interface. The [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) exposes top level functions that let you log three different types of events: * [Search events](#send-search-events) * [Click events](#send-click-events) * [Custom events](#send-custom-events) Regardless of its type, a UA event always requires a cause (an object) and some [metadata](https://docs.coveo.com/en/218/) (a map of strings, or an empty object). ### Send search events Search events are intended to record end-user interactions that trigger queries, such as: * Submitting a search request from the search box * Selecting a facet value Depending on your use case, use the [`logSearchEvent`](https://coveo.github.io/search-ui/globals.html#logsearchevent) or the [`logSearchAsYouTypeEvent`](https://coveo.github.io/search-ui/globals.html#logsearchasyoutypeevent) top-level function to send your own search events. ```javascript const root = document.getElementById("search"); const cause = { name : "mySearchEventName", type : "" }; <1> const metadata = { key1: "value 1", key2: "value 2" }; <2> Coveo.logSearchEvent(root, cause, metadata); Coveo.executeQuery(root); <3> ``` <1> The cause object must implement the [`IAnalyticsActionCause`](https://coveo.github.io/search-ui/interfaces/ianalyticsactioncause.html) interface. However, specifying a `type` other than the empty string (`""`) is only useful when [sending custom events](#send-custom-events). <2> The metadata object must be a map of strings or an empty object (`{}`). <3> You must [execute a query](https://coveo.github.io/search-ui/globals.html#executequery) to log the search event. ### Send click events Click events are intended to record item view and preview actions, such as: * Opening a result link * Opening a result Quick view Use the [`logClickEvent`](https://coveo.github.io/search-ui/globals.html#logclickevent) top level function to send your own click events. ```javascript function getOpenedResult() { // Implementation; returns the opened IQueryResult. } const root = document.getElementById("search"); const cause = { name : "myCustomClickEventName", type : "" }; <1> const metadata = { key1: "value 1", key2: "value 2" }; <2> const result = getOpenedResult(); <3> Coveo.logClickEvent(root, cause, metadata, result); ``` <1> The cause object must implement the [`IAnalyticsActionCause`](https://coveo.github.io/search-ui/interfaces/ianalyticsactioncause.html) interface. However, specifying a `type` other than the empty string (`""`) is only useful when [sending custom events](#send-custom-events). <2> The metadata object must be a map of strings or the empty object (`{}`). <3> When calling the `logClickEvent` function, the last argument must be a reference to the opened or previewed [`IQueryResult`](https://coveo.github.io/search-ui/interfaces/iqueryresult.html). ### Send custom events Custom events are intended to record user interactions that don't trigger a query or open a query result, such as: * Updating end-user preferences * Changing the result list layout ```javascript const root = document.getElementById("search"); const cause = { name: "myCustomEventName", type: "myCustomEventType" }; <1> const metadata = { key1: "value 1", key2: "value 2" }; <2> Coveo.logCustomEvent(root, cause, metadata); ``` <1> The cause object must implement the [`IAnalyticsActionCause`](https://coveo.github.io/search-ui/interfaces/ianalyticsactioncause.html) interface. The [`type`](https://coveo.github.io/search-ui/interfaces/ianalyticsactioncause.html#type) value can be used to group similar custom events in UA reports. <2> The metadata object must be a map of strings or an empty object (`{}`). ## Modify the metadata to send with Coveo Analytics events It can be useful to add or modify metadata to send along with the standard UA events logged by the `Analytics` component. You can do so by [attaching a handler](https://docs.coveo.com/en/417#attaching-event-handlers) on the [`changeAnalyticsCustomData`](https://coveo.github.io/search-ui/classes/analyticsevents.html#changeanalyticscustomdata) event. ```javascript function getUserRole() { // Implementation; returns a string (for example, "Admin", "Developer"). }   const root = document.getElementById("search"); root.addEventListener("changeAnalyticsCustomData", (args) => { if (args.detail.type === "SearchEvent") { <1> args.detail.metaObject["userRole"] = getUserRole(); <2> } });   // ...   Coveo.init(root); <3> ``` <1> All `changeAnalyticsCustomData` event handlers receive an [`IChangeAnalyticsCustomDataEventArgs`](https://coveo.github.io/search-ui/interfaces/ichangeanalyticscustomdataeventargs.html) object as an argument. In this example, we read the [`type`](https://coveo.github.io/search-ui/interfaces/ichangeanalyticscustomdataeventargs.html#type) property of this object to only modify search events. <2> Some properties of the `IChangeAnalyticsCustomDataEventArgs` object, such as [`metaObject`](https://coveo.github.io/search-ui/interfaces/ichangeanalyticscustomdataeventargs.html#metaobject), can be modified. In this example, we add (or modify) the arbitrary `userRole` key-value pair in the event's metadata object. <3> You should always register event handlers before the [`init`](https://coveo.github.io/search-ui/globals.html#init) call of your search interface. ## Anonymize UA data If the users of your search interface are authenticated, you may want to hash their identities to ensure that they can't be identified in UA data. To do so, set the [`anonymous`](https://coveo.github.io/search-ui/components/analytics.html#options.anonymous) option to true on the `Analytics` component. ```html ``` ## Disable and enable analytics Coveo UA uses the `coveo_visitorId` cookie to track individual users and sessions. Although the `[visitorId](https://docs.coveo.com/en/273/)` query parameter has been deprecated, the cookie's name has not been changed to ensure compatibility. When implementing a cookie policy, you may need to disable UA tracking for end users under specific circumstances (for example, when a user opts out of cookies). To do so, you can call the [`disable`](https://coveo.github.io/search-ui/components/analytics.html#disable) method on the `Analytics` component. To re-enable UA tracking, call the [`enable`](https://coveo.github.io/search-ui/components/analytics.html#enable) method. ```javascript let analytics = document.querySelector(".CoveoAnalytics"); analytics = Coveo.get(analytics); analytics.disable(); // Or analytics.enable(); ``` > **Important** > > Coveo ML features require UA data to function. > Therefore, disabling UA tracking for many users can have disastrous consequences on the relevance of a search interface. To clear local session information from the browser without disabling analytics completely, use the [`clearLocalData`](https://coveo.github.io/search-ui/globals.html#clearlocaldata) function. To disable usage analytics completely in a JavaScript Search Framework interface, the simplest way to do so is to not initialize an [`Analytics`](https://coveo.github.io/search-ui/components/analytics.html) component at all. ## What's next? You may want to use the `Analytics` component along with a data layer object and Google Tag Manager to [log search page UA data to Google Analytics](https://docs.coveo.com/en/2943/).