Support Menu

Coveo component Analytics

Coveo Analytics Component (CoveoAnalytics)

The Analytics component logs user actions performed in the search interface and sends 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 Sending Custom Analytics Events for more advanced use cases.

Index

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 this option is true, the Coveo Usage Analytics Platform 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.

Markup configuration example(s) :
data-anonymous='true'
data-anonymous='false'

endpoint

endpoint: string

Specifies the URL of the usage analytics logger to cover exceptional cases in which this location could differ from the default Coveo Cloud Usage Analytics endpoint (https://usageanalytics.coveo.com).

Default value is https://usageanalytics.coveo.com.

Markup configuration example(s) :
data-endpoint='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 company's public community site.

Default value is 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 Platform.

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'

Methods

debugInfo

  • debugInfo(): any

disable

  • disable(): void
  • Disable the component. Normally this means that the component will not execute handlers for the framework events (query events, for example). Component are enabled by default on creation.

    Returns void

enable

  • enable(): void
  • Enable the component. Normally this means that the component will execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

    Returns void

getBindings

logClickEvent

  • Logs a Click event. You can understand click events as item views (e.g., clicking on a ResultLink or opening a Quickview).

    This event is logged immediately on the service.

    Parameters

    • actionCause: IAnalyticsActionCause

      Describes 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 API 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 custom 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 the user has clicked.

    • Default value element: HTMLElement = this.element

      The HTMLElement that the user has clicked in the interface.

    Returns void

logCustomEvent

  • Logs a Custom event on the service. You can use custom events to create custom reports, or to track events that are not queries or item views.

    Type parameters

    • T

    Parameters

    • actionCause: IAnalyticsActionCause

      Describes 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 API 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.

    Returns void

logSearchAsYouType

  • Logs a SearchAsYouType event on the service, using an IAnalyticsActionCause and a meta object.

    This method is very similar to the logSearchEvent method, except that logSearchAsYouType is, by definition, more frequently called.

    The PendingSearchAsYouTypeEvent takes care of logging only the "relevant" last event: an event that occurs after 5 seconds elapse without any event being logged, or an event that occurs after another part of the interface triggers a search event. This avoids logging every single partial query, which would make the reporting very confusing.

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

    See Sending Custom Analytics Events.

    Type parameters

    • T

    Parameters

    • actionCause: IAnalyticsActionCause

      Describes 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 API 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 event on the service, using an AnalyticsActionCause and a meta object.

    Note that the search event is only sent to the service when the query successfully returns, not immediately after calling this method. Therefore, it is important to call this method before executing the query. Otherwise the service will log no Search event and you will get a warning message in the console.

    See Sending Custom Analytics Events.

    Type parameters

    • T

    Parameters

    • actionCause: IAnalyticsActionCause

      Describes 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 API 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

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

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

type

{Coveo.ComponentEvents}

client

A reference to the analyticsClient, which performs the heavy duty part of logging the actual events on the service.

componentOptionsModel

componentOptionsModel: ComponentOptionsModel

Contains the state of options for differents component. Mainly used by ResultLink.

componentStateModel

componentStateModel: ComponentStateModel

Contains the state of different component (enabled vs disabled). Allows to get/set values. Trigger 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.

usageAnalytics

usageAnalytics: IAnalyticsClient

A reference to the Analytics.client.

Static ID

ID: string

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

Constructors

constructor

  • Creates a new Analytics component. Creates the IAnalyticsClient.

    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