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 JavaScript Search Framework Usage Analytics for an introduction.

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

Index

Methods

Properties

Accessors

Component Options

Constructors

Methods

clearLocalData

  • clearLocalData(): void

debugInfo

  • debugInfo(): any

disable

  • disable(): void

enable

  • enable(): void

getBindings

getOriginContext

  • getOriginContext(): string

getUserDisplayName

  • getUserDisplayName(): string

logClickEvent

  • 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

  • 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

  • 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

  • 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

  • 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

    Returns void

setOriginContext

  • setOriginContext(originContext: string): void

  • 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

  • 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

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

type

{Coveo.ComponentEvents}

client

client: IAnalyticsClient

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

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

componentStateModel

componentStateModel: ComponentStateModel

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

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

type

{boolean}

logger

logger: Logger

Allows component to log in the dev console.

queryController

queryController: QueryController

Contains the singleton that allows to trigger queries.

queryStateModel

queryStateModel: QueryStateModel

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

A reference to the root HTMLElement (the SearchInterface).

searchInterface

searchInterface: SearchInterface

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

Static ID

ID: string

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

Accessors

usageAnalytics

Component Options

anonymous

anonymous: boolean

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

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

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 default, the value is https://analytics.cloud.coveo.com/rest/ua, or https://analytics-<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

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

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

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

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

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

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

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

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

  • 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