UsageAnalytics Apex Class

This is for:

Developer System Administrator

In this article

AnalyticsApi

Coveo for Salesforce 3.38 (August 2019)

You can use the UsageAnalytics Apex Class to send usage analytics data to Coveo.

You can also look at the AnalyticsApiClient Apex Class.

AnalyticsApi

Sends usage analytics data to Coveo.

Methods

These methods exist for every specific event category listed below (Search Event, Click Event, and Custom Event).

withParam

Adds a parameter to the event by providing a key-value pair.

CoveoV2.AnalyticsApi.SearchEvent <MY_SEARCH_EVENT> = new CoveoV2.AnalyticsApi.SearchEvent(
    <MY_SEARCH_API_RESPONSE>,
    '<LANGUAGE>',
    '<QUERY_TEXT>',
    '<ACTION_CAUSE>'
);

<MY_SEARCH_EVENT>.withParam('<FOO>', '<BAR>');

// Now MY_SEARCH_EVENT.params.get('FOO') => 'BAR'

Where you replace:

<MY_SEARCH_EVENT> by the name of the search event.
<MY_SEARCH_API_RESPONSE> by the response received and parsed from the Search API. It’s the response to a query that have been sent (see SearchApiResponse Apex Class).
<LANGUAGE> by the language from which the usage analytics event originates.
<QUERY_TEXT> by the original basic query expression (q) in the corresponding search request.
<ACTION_CAUSE> by the type of operation that triggered the event (for example, interfaceLoad).
<FOO> and <BAR> by a key-value pair.

withParamsMap

Adds many parameters to the event by providing a map.

<MY_SEARCH_EVENT>.withParamsMap(new Map<String,Object> { 'foo' => 'bar' });
// Now MY_SEARCH_EVENT.params.get('foo') => 'bar'

Where you replace <MY_SEARCH_EVENT> by the name of the search event.

withCustomData

Adds a key-value pair to the customData of the analytics event.

<MY_EVENT>.withCustomData('<FOO>', '<BAR>');
// Now MY_EVENT.params.get('customData') => Map<String,Object> that contains 'foo' => 'bar'

Where you replace:

<MY_EVENT> by the name of the usage analytics event.
<FOO> and <BAR> by a key-value pair.

stringify

Stringifies the event into a JSON string for sending to the analytics API.

Search Event

When an end user triggers a query to the Search API, a search event is recorded (see Event Categories).

You can create a search event from a Search API response:

CoveoV2.AnalyticsApi.SearchEvent mySearchEvent = new CoveoV2.AnalyticsApi.SearchEvent(
    <MY_SEARCH_API_RESPONSE>,
    '<LANGUAGE>',
    '<QUERY_TEXT>',
    '<ACTION_CAUSE>'
);

Where you replace:

<MY_SEARCH_API_RESPONSE> by the response received and parsed from the Search API. It’s typically the result of a sent query (see SearchApiResponse Apex Class).
<LANGUAGE> by the language of the search interface from which the search event originates (see language (string)).
<QUERY_TEXT> by the original basic query expression (q) in the corresponding search request (see queryText (string)).
<ACTION_CAUSE> by the identifier of the end-user action that triggered a query and caused the search interface to log a usage analytics event (see actionCause (string)).

For more information, see a complete example.

Click Event

When the end user opens or previews a result, the search interface logs a click event (see Event Categories).

You can create a click event from a Search API response:

CoveoV2.AnalyticsApi.ClickEvent myClickEvent = new CoveoV2.AnalyticsApi.ClickEvent(
    <MY_SEARCH_API_RESULT>,
    '<LANGUAGE>',
    '<MY_SEARCH_QUERY_UID>',
    '<ACTION_CAUSE>'
);

Where you replace:

<MY_SEARCH_API_RESULT> by the SearchApiResult to build the event from. It’s a CoveoV2.SearchApiResult that you can get from a CoveoV2.SearchApiResponse.
<LANGUAGE> by the language of the search interface from which the click event originates (see language (string)).
<MY_SEARCH_QUERY_UID> by the unique identifier of the query which led the search interface to log the click event. It can be found in a CoveoV2.SearchApiResponse, it corresponds to the searchUid. We recommend that you use the searchUid in the response of the corresponding search request to the Search API (see searchQueryUid (string)).
<ACTION_CAUSE> by the identifier of the end-user action that triggered a query and caused the search interface to log a usage analytics event (see actionCause (string)).

For more information, see a complete example.

Custom Event

Typically, when the end user interacts with the search interface, but that’s neither a search nor a click, there should be a custom event (see Event Categories).

You can create a custom event from a Search API response:

CoveoV2.AnalyticsApi.CustomEvent myCustomEvent = new CoveoV2.AnalyticsApi.CustomEvent(
    '<MY_EVENT_TYPE>',
    '<MY_EVENT_VALUE>',
    '<LANGUAGE>'
);

Where you replace:

<MY_EVENT_TYPE> by the custom event type (see eventType (string)).
<MY_EVENT_VALUE> by the custom event value (see eventValue (string)).
<LANGUAGE> by the language of the search interface from which the custom event originates (see language (string)).

For more information, see a complete example.