UsageAnalytics Apex Class

Coveo for Salesforce 3.38 (August 2019)

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

You can also look at the AnalyticsApiClient Apex Class.

AnalyticsApi

Sends usage analytics data to the Coveo Cloud.

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 (e.g., 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 <MY_SEARCH_EVENT> = new CoveoV2.AnalyticsApi.SearchEvent(
    <MY_SEARCH_API_RESPONSE>,
    '<LANGUAGE>',
    '<QUERY_TEXT>',
    '<ACTION_CAUSE>'
);
CoveoV2.AnalyticsApiClient.Response resp = CoveoV2.AnalyticsApiClient.logSearchEvent(mySearchEvent, '<MY_VISITOR_ID>');

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 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)).

  • <MY_VISITOR_ID> by the unique identifier of the visitor who performed search actions. It’s contained in every response when a usage analytics is logged, and keeps the same value throughout the visit. Leave the value empty to have one generated automatically at the first event of a visit (see Visitor ID).

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 <MY_CLICK_EVENT> = new CoveoV2.AnalyticsApi.ClickEvent(
    <MY_SEARCH_API_RESULT>,
    '<LANGUAGE>',
    '<MY_SEARCH_QUERY_UID>',
    '<ACTION_CAUSE>'
);
CoveoV2.AnalyticsApiClient.Response resp = CoveoV2.AnalyticsApiClient.logClickEvent(<MY_CLICK_EVENT>, '<MY_VISITOR_ID>');

Where you replace:

  • <MY_CLICK_EVENT> by the name of the click event.

  • <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)).

  • <MY_VISITOR_ID> by the unique identifier of the visitor who performed search actions. It’s contained in every response when a usage analytics is logged, and keeps the same value throughout the visit. Leave the value empty to have one generated automatically at the first event of a visit (see Visitor ID).

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.ClickEvent <MY_CUSTOM_EVENT> = new CoveoV2.AnalyticsApi.<MY_CUSTOM_EVENT>(
    '<MY_EVENT_TYPE>',
    '<MY_EVENT_VALUE>',
    '<LANGUAGE>'
);
CoveoV2.AnalyticsApiClient.Response resp = CoveoV2.AnalyticsApiClient.logCustomEvent(myCustomEvent, '<MY_VISITOR_ID>');

Where you replace:

  • <MY_CUSTOM_EVENT> by the name of the custom event.

  • <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)).

  • <MY_VISITOR_ID> by the unique identifier of the visitor who performed search actions. It’s contained in every response when a usage analytics is logged, and keeps the same value throughout the visit. Leave the value empty to have one generated automatically at the first event of a visit (see Visitor ID).

What's Next for Me?