# Coveo Analytics Component (CoveoAnalytics)

The `Analytics` component can log user actions performed in the search interface and send them to a REST web service exposed through the Coveo Cloud Platform.

You can use analytics data to evaluate how users are interacting with your search interface, improve relevance and produce analytics dashboards within the Coveo Cloud Platform.

See Step 7 - Usage Analytics of the Getting Started with the JavaScript Search Framework V1 tutorial for an introduction to usage analytics.

See also Logging Your Own Search Events for more advanced use cases.

## Index

### Methods

- clearLocalData
- debugInfo
- disable
- enable
- getBindings
- logClickEvent
- logCustomEvent
- logSearchAsYouType
- logSearchEvent
- pushToGtmDataLayer
- setOriginContext
- get

### Properties

- bind
- client
- componentOptionsModel
- componentStateModel
- disabled
- logger
- queryController
- queryStateModel
- root
- searchInterface
- ID

### Accessors

- usageAnalytics

### Component Options

- anonymous
- autoPushToGtmDataLayer
- endpoint
- gtmDataLayerName
- organization
- searchHub
- splitTestRunName
- splitTestRunVersion
- token
- user
- userDisplayName

### Constructors

- constructor

## Methods

### clearLocalData

- clearLocalData(): void

- - Defined in ui/Analytics/Analytics.ts :411

  Removes all session information stored in the browser (e.g., analytics visitor cookies, action history, etc.)

  availablesince

    October 2019 Release (v2.7219)

  #### Returns void

### debugInfo

- debugInfo(): any

- Inherited from BaseComponent.debugInfo

  - Defined in ui/Base/BaseComponent.ts :41

  Return the debug info about this component.

  #### Returns any

### disable

- disable(): void

- Overwrites BaseComponent.disable

  - Defined in ui/Analytics/Analytics.ts :422

  Disables the component and clears local data by running `clearLocalData`.

  #### Returns void

### enable

- enable(): void

- Overwrites BaseComponent.enable

  - Defined in ui/Analytics/Analytics.ts :396

  Re-enables the component if it was previously disabled.

  #### Returns void

### getBindings

- getBindings(): IComponentBindings

- Inherited from Component.getBindings

  - Defined in ui/Base/Component.ts :328

  Return the bindings, or environment, for the current component.

  #### Returns IComponentBindings

### logClickEvent

- logClickEvent(actionCause: IAnalyticsActionCause, meta: IAnalyticsDocumentViewMeta, result: IQueryResult, element?: HTMLElement): void

- - Defined in ui/Analytics/Analytics.ts :370

  Logs a `Click` usage analytics event.

  A `Click` event corresponds to an item view (e.g., clicking on a ResultLink or opening a Quickview).

  `Click` events are immediately sent to the Coveo Usage Analytics service.

  Note:

  > When logging custom `Click` events, you should use the `Coveo.logClickEvent` top-level function rather than calling this method directly from the `Analytics` component instance. See Logging Your Own Click Events.

  #### Parameters

  - ##### actionCause: IAnalyticsActionCause

    The cause of the event.

  - ##### meta: IAnalyticsDocumentViewMeta

    The metadata which you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts uppercase characters to lowercase characters in key names. Each value must be a simple string. You do not have to pass an IAnalyticsDocumentViewMeta as meta when logging a `Click` event. You can actually send any arbitrary meta. If you do not need to log metadata, you can simply pass an empty JSON ( `{}` ).

  - ##### result: IQueryResult

    The result that was clicked.

  - ##### Default value element: HTMLElement = this.element

    The HTMLElement that the user has clicked in the interface. Default value is the element on which the `Analytics` component is bound.

  #### Returns void

### logCustomEvent

- logCustomEvent<T>(actionCause: IAnalyticsActionCause, meta: T, element?: HTMLElement, result?: IQueryResult): void

- - Defined in ui/Analytics/Analytics.ts :342

  Logs a `Custom` usage analytics event on the service.

  You can use `Custom` events to create custom reports, or to track events which are neither queries (see `logSearchEvent` and `logSearchAsYouType`), nor item views (see `logClickEvent`).

  Note:

  > When logging `Custom` events, you should use the `Coveo.logClickEvent` top-level function rather than calling this method directly from the `Analytics` component instance. See Logging Your Own Custom Events.

  #### Type parameters

  - #### T

  #### Parameters

  - ##### actionCause: IAnalyticsActionCause

    The cause of the event.

  - ##### meta: T

    The metadata which you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( `{}` ).

  - ##### Default value element: HTMLElement = this.element

    The HTMLElement that the user has interacted with for this custom event. Default value is the element on which the `Analytics` component is bound.

  - ##### Optional result: IQueryResult

    The IQueryResult that the custom event is linked to, if any.

  #### Returns void

### logSearchAsYouType

- logSearchAsYouType<T>(actionCause: IAnalyticsActionCause, meta: T): void

- - Defined in ui/Analytics/Analytics.ts :315

  Logs a `SearchAsYouType` usage analytics event.

  This method is very similar to the `logSearchEvent` method, except that `logSearchAsYouType` should, by definition, be called more frequently. Consequently, in order to avoid logging every single partial query, the `PendingSearchAsYouTypeEvent` takes care of logging only the "relevant" last event: an event that occurs after 5 seconds have elapsed without any event being logged, or an event that occurs after another part of the interface triggers a search event.

  It is important to call this method before executing the query. Otherwise, no `SearchAsYouType` event will be logged, and you will get a warning message in the console.

  Note:

  > When logging custom `SearchAsYouType` events, you should use the `Coveo.logSearchAsYouTypeEvent` top-level function rather than calling this method directly from the `Analytics` component instance. See Logging Your Own Search Events.

  #### Type parameters

  - #### T

  #### Parameters

  - ##### actionCause: IAnalyticsActionCause

    The cause of the event.

  - ##### meta: T

    The metadata which you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( `{}` ).

  #### Returns void

### logSearchEvent

- logSearchEvent<T>(actionCause: IAnalyticsActionCause, meta: T): void

- - Defined in ui/Analytics/Analytics.ts :286

  Logs a `Search` usage analytics event.

  A `Search` event is actually sent to the Coveo Usage Analytics service only after the query successfully returns (not immediately after calling this method). Therefore, it is important to call this method before executing the query. Otherwise, the `Search` event will not be logged, and you will get a warning message in the console.

  Note:

  > When logging custom `Search` events, you should use the `Coveo.logSearchEvent` top-level function rather than calling this method directly from the `Analytics` component instance. See Logging Your Own Search Events.

  #### Type parameters

  - #### T

  #### Parameters

  - ##### actionCause: IAnalyticsActionCause

    The cause of the event.

  - ##### meta: T

    The metadata you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores, and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( `{}` ).

  #### Returns void

### pushToGtmDataLayer

- pushToGtmDataLayer(data: IAnalyticsEventArgs): void

- - Defined in ui/Analytics/Analytics.ts :448

  Attempts to push data representing a single Coveo usage analytics event to the Google Tag Manager data layer.

  Note: If the `autoPushToGtmDataLayer` option is set to `true` and the GTM data layer has been properly initialized in the page, this method is called automatically whenever an event is about to be logged to the Coveo Cloud usage analytics service.

  See also the `gtmDataLayerName` option.

  #### Parameters

  - ##### data: IAnalyticsEventArgs

    The data to push.

  #### Returns void

### setOriginContext

- setOriginContext(originContext: string): void

- - Defined in ui/Analytics/Analytics.ts :389

  Sets the Origin Context dimension on the analytic events.

  You can use this dimension to specify the context of your application. Suggested values are "Search", "InternalSearch" and "CommunitySearch"

  Default value is `Search`.

  #### Parameters

  - ##### originContext: string

    The origin context value

  #### Returns void

### Static get

- get(element: HTMLElement, componentClass?: any, noThrow?: boolean): BaseComponent

- Inherited from Component.get

  - Defined in ui/Base/Component.ts :410

  Get the bound component to the given HTMLElement. Throws an assert if the HTMLElement has no component bound, unless using the noThrow argument.
  If there is multiple component bound to the current HTMLElement, you must specify the component class.

  #### Parameters

  - ##### element: HTMLElement

    HTMLElement for which to get the bound component.

  - ##### Optional componentClass: any

    Optional component class. If the HTMLElement has multiple components bound, you must specify which one you are targeting.

  - ##### Optional noThrow: boolean

    Boolean option to tell the method to not throw on error.

  #### Returns BaseComponent

## Properties

### bind

bind: ComponentEvents

Inherited from Component.bind

- Defined in ui/Base/Component.ts :270

Allows the component to bind events and execute them only when it is enabled.

type

  {Coveo.ComponentEvents}

### client

client: IAnalyticsClient

- Defined in ui/Analytics/Analytics.ts :206

A reference to the `AnalyticsClient`, which performs the heavy duty part of sending the usage analytics events to the Coveo Usage Analytics service.

### componentOptionsModel

componentOptionsModel: ComponentOptionsModel

Inherited from Component.componentOptionsModel

- Defined in ui/Base/Component.ts :294

Contains the state of options for different components. Mainly used by ResultLink.

### componentStateModel

componentStateModel: ComponentStateModel

Inherited from Component.componentStateModel

- Defined in ui/Base/Component.ts :282

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

### disabled

disabled: boolean

Inherited from BaseComponent.disabled

- Defined in ui/Base/BaseComponent.ts :23

A disabled component will not participate in the query, or listen to ComponentEvents.

type

  {boolean}

### logger

logger: Logger

Inherited from BaseComponent.logger

- Defined in ui/Base/BaseComponent.ts :18

Allows component to log in the dev console.

### queryController

queryController: QueryController

Inherited from Component.queryController

- Defined in ui/Base/Component.ts :286

Contains the singleton that allows to trigger queries.

### queryStateModel

queryStateModel: QueryStateModel

Inherited from Component.queryStateModel

- Defined in ui/Base/Component.ts :278

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

### root

root: HTMLElement

Inherited from Component.root

- Defined in ui/Base/Component.ts :274

A reference to the root HTMLElement (the SearchInterface).

### searchInterface

searchInterface: SearchInterface

Inherited from Component.searchInterface

- Defined in ui/Base/Component.ts :290

A reference to the root of every component, the SearchInterface.

### Static ID

ID: string

Inherited from BaseComponent.ID

- Defined in ui/Base/BaseComponent.ts :28

The static ID that each component needs in order to be identified.
For example, SearchButton -> static ID: SearchButton -> className: CoveoSearchButton

## Accessors

### usageAnalytics

- get (): IAnalyticsClient

- Inherited from Component.usageAnalytics

  - Defined in ui/Base/Component.ts :343

  A reference to the Analytics.client.

  #### Returns IAnalyticsClient

## Component Options

### anonymous

anonymous: boolean

- Defined in ui/Analytics/Analytics.ts :132

Specifies whether to convert search user identities to unique hash when logging analytics data, so that analytics reviewers and managers will not be able to clearly identify which user is performing which query.

When you set this option to `true`, the Coveo Usage Analytics service can still properly differentiate sessions made by anonymous users from sessions made by users authenticated in some way on the site containing the search page.

Default value is `false`.

Default

  `false`

Markup configuration example(s) :

    data-anonymous='true'
    data-anonymous='false'

### autoPushToGtmDataLayer

autoPushToGtmDataLayer: boolean

- Defined in ui/Analytics/Analytics.ts :187

Whether to automatically attempt to push Coveo usage analytics events to the Google Tag Manager data layer.

See also `gtmDataLayerName`.

Default

  `false`

Available since

  July 2019 Release (v2.6459)

Markup configuration example(s) :

    data-auto-push-to-gtm-data-layer='true'
    data-auto-push-to-gtm-data-layer='false'

### endpoint

endpoint: string

- Defined in ui/Analytics/Analytics.ts :111

Specifies the URL of the Usage Analytics service. You do not have to specify a value for this option, unless the location of the service you use differs from the default Coveo Cloud Usage Analytics endpoint.

By deault, the value is `https://platform.cloud.coveo.com/rest/ua`, or `https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/rest/ua` if you have configured your search endpoint to implement data residency outside of the United States.

Markup configuration example(s) :

    data-endpoint='foo'

### gtmDataLayerName

gtmDataLayerName: string

- Defined in ui/Analytics/Analytics.ts :199

The name of the Google Tag Manager data layer initialized in the page.

See also `autoPushToGtmDataLayer`.

Note: Setting this option is only useful if the GTM data layer was renamed in the page.

Default: `dataLayer`

Default

  `dataLayer`

Markup configuration example(s) :

    data-gtm-data-layer-name='foo'

### organization

organization: string

- Defined in ui/Analytics/Analytics.ts :178

Specifies the organization bound to the access token. This is necessary when using an access token, because a single access token can be associated to more than one organization.

Default value is `undefined`, and the value of this parameter will fallback to the organization used for the search endpoint.

Markup configuration example(s) :

    data-organization='foo'

### searchHub

searchHub: string

- Defined in ui/Analytics/Analytics.ts :148

Sets the Search Hub dimension on the search events.

The Search Hub dimension is typically a name that refers to a specific search page. For example, you could use the `CommunitySite` value to refer to a search page on a public community site.

Note:

> If you wish to use the search hub dimension for security reasons (e.g., to provide different query suggestions for internal and external users), you should specify the search hub when generating the search token for the end user (in safe, server-side code), rather than setting it with this option (see Search Token Authentication).

Default value is `default`.

Default

  `default`

Markup configuration example(s) :

    data-search-hub='foo'

### splitTestRunName

splitTestRunName: string

- Defined in ui/Analytics/Analytics.ts :158

Specifies the name of the split test run that the search page is part of.

You can use this dimension to perform A/B testing using different search page layouts and features inside the Coveo Query pipeline.

Default value is `undefined` and no split test run name is reported to the Coveo Usage Analytics service.

Markup configuration example(s) :

    data-split-test-run-name='foo'

### splitTestRunVersion

splitTestRunVersion: string

- Defined in ui/Analytics/Analytics.ts :168

Specifies the version name for the page when a split test run is active.

When reporting on A/B testing analytics data, this value specifies the test run version name that was presented to the user.

Default value is `undefined`

Markup configuration example(s) :

    data-split-test-run-version='foo'

### token

token: string

- Defined in ui/Analytics/Analytics.ts :100

Specifies the token to use to access the usage analytics endpoint.

Default value is `undefined`, and the component uses the search token.

Markup configuration example(s) :

    data-token='foo'

### user

user: string

- Defined in ui/Analytics/Analytics.ts :86

Specifies the name of the user for the usage analytics logs.

Default value is `undefined`

Markup configuration example(s) :

    data-user='foo'

### userDisplayName

userDisplayName: string

- Defined in ui/Analytics/Analytics.ts :93

Specifies the user display name for the usage analytics logs.

Default value is `undefined`

Markup configuration example(s) :

    data-user-display-name='foo'

## Constructors

### constructor

- new Analytics(element: HTMLElement, options?: IAnalyticsOptions, bindings?: IComponentBindings): Analytics

- Overwrites Component.constructor

  - Defined in ui/Analytics/Analytics.ts :208

  Creates a new `Analytics` component. Creates the `AnalyticsClient`.

  #### Parameters

  - ##### element: HTMLElement

    The HTMLElement on which the component will be instantiated.

  - ##### Default value options: IAnalyticsOptions = {}

    The options for the `Analytics` component.

  - ##### Optional bindings: IComponentBindings

    The bindings that the component requires to function normally. If not set, these will be automatically resolved (with a slower execution time).

  #### Returns Analytics