Skip to end of metadata
Go to start of metadata

In this topic:

The Analytics component logs user actions performed in a Coveo JavaScript 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 to help improve relevance and produce analytics dashboards within the Coveo Cloud Platform (see Coveo Cloud Usage Analytics and Setting Up Cloud Usage Analytics Logging by the JavaScript Search With an On-Premises Index). 

In some scenarios, you may want to send additional data to the Coveo Cloud usage analytics. The Coveo JavaScript Search Framework offers helpers to communicate with the Coveo Analytics REST API, so you do not have to write code to call the API directly. 

Defining Analytics Events and Metadata

You must first define your analytics action cause and its associated metadata.

An analytics action cause should have a unique name attribute as well as a more generic type attribute (see IAnalyticsActionCause). The type attribute allows you to group similar event types when doing reporting (e.g.,  a searchbox type could allow you to filter all events performed from a Searchbox). 

Note that it is useful to specify a type only when logging a Custom event. When logging a Click, Search or SearchAsYouType event, the type attribute is simply ignored (see Sending Events).

Metadata is a JSON that contains zero or more key-value pairs. You can use metadata to create custom dimensions (see Managing Dimensions on Custom Metadata). You can add as many key-value pairs as you need in the metadata JSON.

Each metadata key must match the [A-Za-z0-9_ ]* regex for the Coveo Analytics API to accept it. However, you should know that the Coveo Analytics API actually reformats each metadata key to make it match the c_[a-z0-9_]* regex. This means that if you use F00 b4r as a metadata key, the Coveo Analytics API transforms it to c_f00_b4r.

Each metadata value must be a simple string. You cannot use other types (boolean, number, etc.) or complex objects as metadata values.

Metadata is optional. If you do not wish to log any metadata, you can simply pass an empty JSON ({}).

Example:
Generic example


Sending Events

You can log analytics events of the following types (see Usage Analytics Recorded Events):

  • Search
  • Click
  • SearchAsYouType
  • Custom

You should always log Search and SearchAsYouType events before an executeQuery call. This allows the Analytics component to queue the event and wait for the query to successfully return before sending the event to the Coveo Usage Analytics API. If you try calling logSearchEvent or logSearchAsYouTypeEvent without following this call with a query, you will see in your browser console that no event is actually sent.

Icon

When sending events to the Usage Analytics service, you should always send them in the order in which they happen. Not doing so might lead to some events being lost or not logged appropriately.

While there are three different, but equivalent ways to send events to the Coveo Usage Analytics API (see Interacting with the Framework and Its Components), all of the following code samples use the Coveo.$$ function to do so.

Sending a Custom Event

When sending a Custom event, remember that the type attribute you specify in your IAnalyticsActionCause makes it possible to group similar Custom events together in usage analytics reports.

Optionally, you can also log the HTML element that the user interacted with to trigger the Custom event.

Example:

Consider the following markup:

Calling this function sends a Custom event to the Coveo Usage Analytics service.

 

See logCustomEvent.

 

Sending a Custom Search Event

When sending a custom Search event, remember to always call the logSearchEvent method before the executeQuery method. Otherwise, no event is sent to the Coveo Usage Analytics API.

Also remember that it is not useful to specify a type attribute in your analytics action cause when sending a custom Search event, as the Coveo Usage Analytics API ignores this attribute.

 

Icon

When an Analytics component is present on your page, executing the query without previously calling either logSearchEvent or logSearchAsYouType displays the following warning message in the console:

A search was triggered, but no analytics event was logged. If you wish to have consistent analytics data, consider logging a search event using the methods provided by the framework.

Example:

Consider the following markup:

Calling this function sends a custom Search event to the Coveo Usage Analytics service.

See logSearchEvent.

Sending a Custom SearchAsYouType Event

When sending a custom SearchAsYouType event, remember to always call the logSearchAsYouType method before the executeQuery method. Otherwise, no event is sent to the Coveo Usage Analytics API.

Also remember that it is not useful to specify a type attribute in your analytics action cause when sending a custom SearchAsYouType event, as the Coveo Usage Analytics API ignores this attribute.

 

Icon

When an Analytics component is present if your page, executing the query without previously calling either logSearchEvent or logSearchAsYouType displays the following warning message in the console:

A search was triggered, but no analytics event was logged. If you wish to have consistent analytics data, consider logging a search event using the methods provided by the framework.

Example:

Consider the following markup:

Calling this function sends a custom SearchAsYouType event to the Coveo Usage Analytics service.

See logSearchAsYouType.

Sending a Custom Click Event

When logging a custom Click event, the result parameter represents the QueryResult that the user has clicked.

Optionally, you can also log the HTML element that the user clicked to trigger the custom Click event.

Example:

Consider the following markup:

Assuming clickedResult is the QueryResult that the end user clicked, calling this function sends a custom Click event to the Coveo Usage Analytics service.

Icon

Since a Click event normally logs an item view, the Analytics.logClickEvent method specifies that its meta argument should be an IAnalyticsDocumentViewMeta. The Coveo JavaScript Search Framework models the meta argument of all its out of the box Click events on this interface.

When logging your own custom Click events, the metadata you send does not have to stick to this model, though. You can send any arbitrary metadata you need for your custom Click events, as long as you use valid keys and values (see Defining Analytics Events and Metadata).

See logClickEvent.

Code Samples

Example:

The following example shows how you could bind a click event handler to a Cancel Help Request button to send a Custom case deflection event to the Coveo Usage Analytics service.

  • No labels