UsageAnalytics Apex class
UsageAnalytics Apex class
You can use the UsageAnalytics
Apex class to send usage analytics data to Coveo.
|
Note
You can also look at the |
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 aCoveoV2.SearchApiResult
that you can get from aCoveoV2.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 aCoveoV2.SearchApiResponse
and it corresponds to thesearchUid
. Use thesearchUid
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.