--- title: Capture search events (Coveo UA) slug: n7o80165 canonical_url: https://docs.coveo.com/en/n7o80165/ collection: coveo-for-commerce source_format: adoc --- # Capture search events (Coveo UA) > **Important** > > We strongly recommend that all new Commerce implementations use the [Event Protocol](https://docs.coveo.com/en/o1n91230/) to log events. This article explains how to capture a [search event](https://docs.coveo.com/en/1502/) and send the information to Coveo along with the required [fields](https://docs.coveo.com/en/200/). ## When to capture a search event The _search event_ is by far one of the most commonly logged commerce [Coveo Analytics events](https://docs.coveo.com/en/260/). Any time a ranked list of products is shown to a [visitor](https://docs.coveo.com/en/nbub9475/), whether it be from submitting a search [query](https://docs.coveo.com/en/231/), navigating to a listings page, or viewing a product recommendations carousel, a search [event](https://docs.coveo.com/en/260/) must be sent to the [Coveo Platform](https://docs.coveo.com/en/186/) to capture user intent and begin tracing the user journey. The [event](https://docs.coveo.com/en/260/) will be used to measure [attribution](https://docs.coveo.com/en/m7l98577/) from a search results page, a product listings page, or a recommendations component. ## Headless controllers and Atomic components [Headless](https://docs.coveo.com/en/headless/latest/) and [Atomic](https://docs.coveo.com/en/atomic/latest/) components log search [events](https://docs.coveo.com/en/260/) under the hood on your behalf. You don't need to manually log search [events](https://docs.coveo.com/en/260/) if you build your UI with these technologies. The following sections provide guidance on the necessary configurations to ensure that search [events](https://docs.coveo.com/en/260/) are appropriately logged. ### Initialization configuration This section is dedicated to explaining the initial configuration of your components. Specifically, we will discuss the importance of properly setting the `[searchHub](https://docs.coveo.com/en/1342/)`, `pipeline`, and `language` parameters. #### Set the search hub Depending on the type of interface the event originates from, there are [naming conventions for the search hub value](https://docs.coveo.com/en/n89e0266#search-hub-naming-conventions) you need to follow. We recommend setting the search hub on Headless and Atomic to control how the queries are processed in the [Coveo Administration Console](https://docs.coveo.com/en/183/) (see [Query routing](https://docs.coveo.com/en/n89e0266#query-routing)). When configured, the frameworks will automatically send the value in search events in the `originLevel1` field. You can either configure the search hub in the [authentication method](https://docs.coveo.com/en/n89e0266#defining-the-search-hub-in-the-authentication), or set it at [interface level](https://docs.coveo.com/en/n89e0266#defining-the-search-hub-at-the-interface-level). #### Language In Coveo Machine Learning (ML) models, [multilingual search and recommendations are supported](https://docs.coveo.com/en/1956#supported-languages-for-machine-learning-models), allowing you to deliver personalized and relevant content to users in different languages. To ensure accurate and effective language-based results, it's important to consider the language of the search query and align it with the language specified in the various usage analytics events. Headless and Atomic automatically set the language of usage analytics events to the language of the search query. The language is set to `en` by default; however, if your use case serves content in multiple languages, we recommend specifying the language by setting the value of the `locale` field when initializing your components. The [`locale`](https://docs.coveo.com/en/13#operation/searchUsingPost-locale) field is formed by combining the language and region values with a hyphen, like `en-US`, where `en` represents the language and `US` represents the region. > **Note** > > The value of the [`language`](https://docs.coveo.com/en/1502#language-string) field must be a two letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. #### Query pipeline When the interface sends a query to your [Coveo organization](https://docs.coveo.com/en/185/), it goes through a specific [Coveo query pipeline](https://docs.coveo.com/en/180/) before reaching the index. This can be done by specifying a Search Hub and then using [condition based routing](https://docs.coveo.com/en/1666#condition-based-routing-recommended) in the Administration Console to target a specific pipeline. A query pipeline uses its rules to transform that query and apply specific features following a specific order of execution. While it's not necessary to specify the query pipeline, we recommend that you do, as it allows you to filter and segregate events when looking at usage analytics reports. #### For Headless The following code snippet explains how to set the `[searchHub](https://docs.coveo.com/en/1342/)`, and `language` [fields](https://docs.coveo.com/en/200/) when initializing your [Headless](https://docs.coveo.com/en/lcdf0493/) search engine. Specify these values using the [`SearchConfigurationOptions`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.SearchConfigurationOptions.html) object, as in the following code sample: ```javascript import { buildSearchEngine } from '@coveo/headless'; export const headlessEngine = buildSearchEngine({ configuration: { organizationId: '', accessToken: '' search: { searchHub: "", locale: "", }, }, }); ``` #### For Atomic The following code snippet explains how to set the `[searchHub](https://docs.coveo.com/en/1342/)`, and `language` [fields](https://docs.coveo.com/en/200/) by setting these properties on the [`atomic-search-interface`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-search-interface\--docs) component: ```html ``` ```html ``` ### Origin levels The `originLevel` feature provides valuable information about the origin of usage analytic events, similar to the Search Hub. Several fields are associated with the `originLevel` feature: * [`originLevel1`](https://docs.coveo.com/en/2064#originlevel1-string) (required): This field should match the value of the Search Hub. If you initialize Headless or Atomic with the SearchHub configuration, this field is automatically set. * [`originLevel2`](https://docs.coveo.com/en/2064#originlevel2-string) (recommended): This field lets you differentiate between different tabs within the search interface if multiple tabs are present. When using the [Tab](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.Tab.html) controller, Headless can automatically populate the `originLevel2` field with the ID specified during the initialization of your controller. ** For the "Search" interface without any tabs, you can send the value "default." ** For the "Listing" page, send the path name of the listing (for example, "my-products/shoes.") ** For "Recs," you can send the value "default." * [`originLevel3`](https://docs.coveo.com/en/2064#originlevel3-string) (recommended): This field represents the URL of the page that redirects the browser to the search interface. It helps you analyze the effectiveness of various entry points leading to the search experience. It's typically extracted from `document.referrer`. During engine initialization, you can set the values for the `originLevel` fields. However, if you need to dynamically modify these values, you have the flexibility to modify the usage analytics data sent to Coveo. You can do so by leveraging the `analyticsClientMiddleware` property of an `AnalyticsConfiguration` to hook into an analytics event payload before it's sent to Coveo. This can be done for both [Headless](https://docs.coveo.com/en/headless/latest/usage/headless-usage-analytics/headless-coveo-ua#modify-the-metadata-to-send-with-coveo-analytics-events) and [Atomic](https://docs.coveo.com/en/atomic/latest/usage/atomic-usage-analytics/atomic-coveo-ua#modify-the-metadata-to-send-with-coveo-analytics-events). ### Custom data Along with the regular [fields](https://docs.coveo.com/en/200/) added by [Headless](https://docs.coveo.com/en/lcdf0493/) and [Atomic](https://docs.coveo.com/en/lcdf0264/), [Coveo Analytics events](https://docs.coveo.com/en/260/) must contain a `[customData](https://docs.coveo.com/en/1341/)` JSON with additional [fields](https://docs.coveo.com/en/200/). While the library adds some [fields](https://docs.coveo.com/en/200/) to this `[customData](https://docs.coveo.com/en/1341/)` JSON, there are other [fields](https://docs.coveo.com/en/200/) that have to be manually added using the [Headless library](https://docs.coveo.com/en/lcdf0493/): > **Note** > > If you're using the [Atomic library](https://docs.coveo.com/en/lcdf0264/), you'll need to [access Headless through Atomic](https://docs.coveo.com/en/atomic/latest/usage/headless-through-atomic/). ### Sending user information If your implementation includes an [authentication](https://docs.coveo.com/en/2120/) mechanism, we highly recommend sending additional [fields](https://docs.coveo.com/en/200/) regarding the [user](https://docs.coveo.com/en/250/) performing the request. To automatically send this [user](https://docs.coveo.com/en/250/)-oriented usage analytics information to the [Coveo Platform](https://docs.coveo.com/en/186/), use a [search token](https://docs.coveo.com/en/56/). This involves generating [search tokens](https://docs.coveo.com/en/1346/) while providing the [`name`](https://docs.coveo.com/en/56#name-string-required), [`userDisplayName`](https://docs.coveo.com/en/56#userdisplayname-string-optional), and [`userGroups`](https://docs.coveo.com/en/56#usergroups-array-of-strings-optional) [fields](https://docs.coveo.com/en/200/). The generated [search token](https://docs.coveo.com/en/1346/) is then used to send requests via [Headless](https://docs.coveo.com/en/lcdf0493/) and [Atomic](https://docs.coveo.com/en/lcdf0264/). > **Note** > > The `name`, `userDisplayName`, and `userGroups` [fields](https://docs.coveo.com/en/200/) are extracted server-side by the [Coveo Platform](https://docs.coveo.com/en/186/), which means that they won't be visible on the **Network** tab if you inspect the outgoing analytics request. To understand how to send [user](https://docs.coveo.com/en/250/) information if [users](https://docs.coveo.com/en/250/) are logged in, and you're utilizing an [API key](https://docs.coveo.com/en/105/) for [authentication](https://docs.coveo.com/en/2120/), see [User tracking and anonymizing UA data](https://docs.coveo.com/en/headless/latest/usage/headless-usage-analytics/headless-ep#disable-and-enable-analytics). ## Capture a search event using Coveo UA library commands We strongly recommend using either the [Headless](https://docs.coveo.com/en/lcdf0493/) or [Atomic](https://docs.coveo.com/en/lcdf0264/) libraries for capturing search [events](https://docs.coveo.com/en/260/) as these libraries are designed to facilitate the logging of such [events](https://docs.coveo.com/en/260/) by automatically including the appropriate [metadata](https://docs.coveo.com/en/218/) and simplifying the implementation process. However, if you choose not to use these libraries or want to track search [events](https://docs.coveo.com/en/260/) on a component that's not powered by Coveo, you can still log search [events](https://docs.coveo.com/en/260/) manually using the [Coveo UA library](https://www.npmjs.com/package/coveo.analytics). The following is an example of the JavaScript code that uses the [Coveo Analytics](https://docs.coveo.com/en/182/) library to send a search [event](https://docs.coveo.com/en/260/): ```js coveoua('send', 'search', { <1> 'actionCause': 'searchboxSubmit', 'queryText': 'shoes', 'responseTime': 23, 'anonymous': true, 'originLevel1': 'MainSearch', 'originLevel2': 'default', 'originLevel3': 'http://localhost:3000/search', 'searchHub': 'MainSearch', 'searchQueryUid': '514970dd-7c76-429f-8e80-6ea2f957f303', 'language': 'en', 'trackingId': 'Sports', }); ``` <1> Send the search [event](https://docs.coveo.com/en/260/), [specifying the various required fields](#search-data-payload-requirements). ### Search data payload requirements The following table lists the fields sent along with the event and the solutions that use these fields. _Search_, _Listings_, and _Recs_ columns refer to whether the ML that powers those solutions needs those data points. The _Reporting_ column is for general reporting purposes that encompasses all solutions. [%header,cols="2,2,4*"] |=== |Field |Priority |Search |Listings |Recs |Reporting |[`actionCause`](https://docs.coveo.com/en/1502#actioncause-string) |Required |[check] |[check] |[check] |[check] |[`anonymous`](https://docs.coveo.com/en/1502#anonymous-boolean) |Required |[check] |[check] |[check] |[check] |[`language`](https://docs.coveo.com/en/1502#language-string)[.footnote]^1^ |Required |[check] |[check] |[check] |[check] |[`numberOfResults`](https://docs.coveo.com/en/1502#numberofresults-unsigned-integer) |Required | | | |[check] |[`queryText`](https://docs.coveo.com/en/1502#querytext-string) |Required |[check] |[check] |[check] |[check] |[`responseTime`](https://docs.coveo.com/en/1502#responsetime-strictly-positive-integer) |Required | | | |[check] |[`searchQueryUid`](https://docs.coveo.com/en/1502#searchqueryuid-string)[.footnote]^2^ |Required |[check] |[check] |[check] |[check] |[`trackingId`](https://docs.coveo.com/en/1502#trackingid-string) |Required |[check] |[check] |[check] |[check] |[`originLevel1`](https://docs.coveo.com/en/1502#originlevel1-string) |Required |[check] |[check] |[check] |[check] |[`originLevel2`](https://docs.coveo.com/en/1502#originlevel2-string) |Recommended |[check] |[check] | |[check] |[`originLevel3`](https://docs.coveo.com/en/1502#originlevel3-string) |Recommended |[check] |[check] | |[check] |[`advancedQuery`](https://docs.coveo.com/en/1502#advancedquery-string) |Recommended |[check] |[check] | |[check] |[`queryPipeline`](https://docs.coveo.com/en/1502#querypipeline-string) |Recommended | | | |[check] |[`splitTestRunName`](https://docs.coveo.com/en/1502#splittestrunname-string) |Recommended | | | |[check] |[`splitTestRunVersion`](https://docs.coveo.com/en/1502#splittestrunversion-string) |Recommended | | | |[check] |[`username`](https://docs.coveo.com/en/1502#username-string)[.footnote]^3^ |Recommended | | | |[check] |[`userDisplayName`](https://docs.coveo.com/en/1502#userdisplayname-string)[.footnote]^3^ |Recommended | | | |[check] |[`userGroups`](https://docs.coveo.com/en/1502#usergroups-string-array)[.footnote]^3^ |Recommended | | | |[check] |[`customData.partialQuery`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs)[.footnote]^4^ |Recommended |[check] | | | |[`customData.partialQueries`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs)[.footnote]^4^ |Recommended |[check] | | | |[`customData.suggestions`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs)[.footnote]^4^ |Recommended | | | |[check] |[`customData.suggestionRanking`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs)[.footnote]^4^ |Recommended | | | |[check] |`facetState`[.footnote]^5^ |Recommended |[check] |[check] | | |=== -- 1. Defaults to English. 2. Refer to [Extract the searchUid](https://docs.coveo.com/en/l2jb0279/). 3. User specific fields which can be sent if the user is authenticated. 4. Field sent when the user interacts with Coveo ML query suggestions. Refer to [Handle Coveo Machine Learning query suggestion selection](https://docs.coveo.com/en/1377#handle-coveo-machine-learning-query-suggestion-selection). 5. Array containing items that represent active facets applied in the search. Refer to [Implement facets](https://docs.coveo.com/en/3199/). -- Refer to [Log search events](https://docs.coveo.com/en/1502/) for more information on the [fields](https://docs.coveo.com/en/200/) discussed above. ## Search event validation To validate that the search [event](https://docs.coveo.com/en/260/) was sent, [use the developer tools for client-side request verification](https://docs.coveo.com/en/n8493503#use-developer-tools-for-client-side-request-verification) to inspect your visit to ensure that everything done using the UI is captured as a set of consistent and coherent [events](https://docs.coveo.com/en/260/). This must occur after the implementation is applied. Inspect the search [event](https://docs.coveo.com/en/260/) through the network browser and ensure that it satisfies the following: ![Barca search event network browser](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/3188_images/barca-search-event-validation-example-1.png) 1 A `search` [event](https://docs.coveo.com/en/260/) is sent whenever the user interacts with the search box or a [facet](https://docs.coveo.com/en/1571/). 2 The [`actionCause`](https://docs.coveo.com/en/1502#actioncause-string) parameter of the search [event](https://docs.coveo.com/en/260/) is set to the correct value. Some common values include: [%header,cols="2"] |=== |User action identifier |Description |[`facetSelect` or `facetDeselect`](https://docs.coveo.com/en/2948#facetselectfacetdeselect-performsearch-refinement) |Selecting or deselecting the [facet](https://docs.coveo.com/en/198/) that re-renders the search results page. |[`facetClearAll`](https://docs.coveo.com/en/2948#facetclearall-performsearch-refinement) |Deselecting all [facets](https://docs.coveo.com/en/198/), re-rendering search. |[`interfaceLoad`](https://docs.coveo.com/en/2948#interfaceload-performsearch) |When a user loads a [search interface](https://docs.coveo.com/en/2741/), for example, when reloading the search results page. |[`omniboxAnalytics`](https://docs.coveo.com/en/2948#omniboxanalytics-performsearch-manual) |When a search result originates from a [query suggestion](https://docs.coveo.com/en/1015/). |[`recommendationInterfaceLoad`](https://docs.coveo.com/en/2948#recommendationinterfaceload) |A [visitor](https://docs.coveo.com/en/nbub9475/) views a recommendation. |[`searchboxSubmit`](https://docs.coveo.com/en/2948#searchboxsubmit-performsearch-manual) |When a user submits search [queries](https://docs.coveo.com/en/231/) in the search box. |[`searchFromLink`](https://docs.coveo.com/en/2948#searchfromlink-performsearch-manual) |A [visitor](https://docs.coveo.com/en/nbub9475/) clicks a navigation link and lands on the search results page. |=== See the [list of action causes](https://github.com/coveo/search-ui/blob/master/src/ui/Analytics/AnalyticsActionListMeta.ts#L321) for analytics purposes. 3 The [`anonymous`](https://docs.coveo.com/en/1502#anonymous-boolean) [field](https://docs.coveo.com/en/200/) is set to the correct value based on the implementation. The default value is `false`. 4 The value of the `[originLevel1](https://docs.coveo.com/en/1337/)` must contain a value to calculate the [attributed](https://docs.coveo.com/en/m7l98577/) value for each [product discovery solution](https://docs.coveo.com/en/o9cf0524/). For example, `search` for search, `listing` for product listings, and `rec` for product recommendations. 5 Ensure that the `searchQueryUid` is unique for every search [event](https://docs.coveo.com/en/260/).