Standard actions and Usage Analytics reference

This is for:

Developer

In this article

Generic actions
Search box actions
Result list actions
Facet actions
Custom filter actions

This article lists some of the most frequent actions you may want to make available in a custom search interface implementation.

The following information is included for each action:

The category of usage analytics event (Search, Click, or Custom) that must be logged when this action is performed (see Log Usage analytics events).
The corresponding actionCause (for Search and Click events) or eventType and eventValue (for Custom events).
The corresponding customData keys, if any.

The actions in this article are grouped into five broad categories:

Generic Actions (initializing a search interface, selecting a tab, etc.)
Search Box Actions (submitting end-user queries, handling Coveo Machine Learning (Coveo ML) Query Suggestions (QS), etc.)
Result List Actions (opening query results, paging query results, etc.)
Facet Actions (toggling facet values directly or indirectly, performing facet search, etc.)
Custom Filter Actions (creating, updating, or interacting with custom/advanced filters)

This article only lists common search interface actions that, when performed, require logging specific usage analytics events. Other frequent actions that don’t have this requirement, such as rendering query results or facets, are therefore not included in this article.

You must ensure that end-user interactions with your custom search interface implementation log usage analytics events in a way that closely resembles what the Coveo Atomic or Headless libraries would do in similar circumstances. Otherwise:

Standard usage analytics reports may become incoherent in the underlying Coveo organization (especially if that organization powers both Coveo Atomic or Headless and custom search interfaces).
Coveo ML models may not function properly, or may require extensive customization.

Generic actions

Initializing a search interface

Action	Usage analytics event	`actionCause`	`customData`
Load a standard search interface	Search	`interfaceLoad`	N/A
Load a recommendation interface	Search	`recommendationInterfaceLoad`	N/A

Selecting a tab

See Implement Tabs.

Action	Usage analytics event	`actionCause`	`customData`
Select a tab	Search	`interfaceChange`	`interfaceChangeTo`

Handling Coveo query pipeline triggers

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Run an `execute` query pipeline trigger	Custom	`queryPipelineTriggers`	`execute`	`executed`
Run a `notify` query pipeline trigger	Custom	`queryPipelineTriggers`	`notify`	`notification`
Run a `query` query pipeline trigger	Custom	`queryPipelineTriggers`	`query`	`query`
Run a `redirect` query pipeline trigger	Custom	`queryPipelineTriggers`	`redirect`	`redirectedTo`

Manage end-user settings

Action	Usage analytics event	`actionCause`	`eventType`	`eventValue`	`customData`
Update end-user preferences	Custom	N/A	`preferences`	`preferencesChange`	`preferenceName`, `preferenceType`
Resolve end-user geolocation	Search	`positionSet`	N/A	N/A	N/A

Handling query errors

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Go back to the previous state after a query returned no results	Custom	`noResults`	`noResultsBack`	N/A
Log a query error	Custom	`errors`	`query`	`aq`, `cq`, `dq`, `errorMessage`, `errorType`, `query`
Go back to the previous state after a query returned an error	Custom	`errors`	`errorBack`	N/A
Reset the search box after a query returned an error	Custom	`errors`	`errorClearQuery`	N/A
Execute the same query again after a query returned an error	Custom	`errors`	`errorRetry`	N/A

See Implement a Search Box.

Submitting End-User Queries

Action	Usage analytics event	`actionCause`	`customData`
Send an end-user query from a non-standalone search box	Search	`searchboxSubmit`	N/A
Execute an end-user query sent from a standalone search box	Search	`searchFromLink`	N/A
Clear a non-standalone search box (and send a blank end-user query as a side effect)	Search	`searchboxClear`	N/A

See Implement a Search Box - Submitting a Query.

Handling Coveo ML Query Suggestions

Action	Usage analytics event	`actionCause`	`customData`
Select a Coveo ML query suggestion from a non-standalone search box	Search	`omniboxAnalytics`	`partialQueries`, `partialQuery`, `suggestionRanking`, `suggestions`
Execute a Coveo ML-suggested query selected from a standalone search box	Search	`omniboxFromLink`	`partialQueries`, `partialQuery`, `suggestionRanking`, `suggestions`
Trigger a search-as-you-type query	Search	`searchAsYouType`	`partialQueries`, `partialQuery`, `suggestionRanking`, `suggestions`

See Implement a Search Box - Providing Coveo Machine Learning Query Suggestions.

Handling field-based Query Suggestions

Action	Usage analytics event	`actionCause`	`customData`
Select a field-based suggestion	Search	`omniboxField`	N/A

See Implement a Search Box - Providing Field-Based Query Completion Suggestions.

Correcting queries

Action	Usage analytics event	`actionCause`	`customData`
Select a query correction suggestion	Search	`didyoumeanClick`	N/A
Trigger an automatically corrected query	Search	`didyoumeanAutomatic`	N/A

See Implement a Search Box - Correcting Queries

Result list actions

See Implement a Result List.

Opening Query Results

Action	Usage analytics event	`actionCause`	`customData`
Open a query result	Click	`documentOpen`	`author`, `contentIdKey`, `contentIdValue`, `documentTitle`, `documentURL`
Open a Coveo ML content recommendation result in a recommendation interface	Click	`recommendationOpen`	`author`, `documentTitle`, `documentURL`
Preview a query result	Click	`documentQuickview`	`author`, `contentIdKey`, `contentIdValue`, `documentTitle`, `documentURL`

See Implement a Result List - Opening Query Results.

Paging query results

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Navigate to a specific page of query results	Custom	`getMoreResults`	`pagerNumber`	`pagerNumber`
Navigate to the next page of query results	Custom	`getMoreResults`	`pagerNext`	`pagerNumber`
Navigate to the previous page of query results	Custom	`getMoreResults`	`pagerPrevious`	`pagerNumber`
Scroll down to get more results in infinite scroll mode	Custom	`getMoreResults`	`pagerScrolling`	N/A
Select the number of query results to display per page	Custom	`getMoreResults`	`pagerResize`	`currentResultsPerPage`

See Implement a Result List - Paging Query Results.

Sorting query results

Action	Usage analytics event	`actionCause`	`customData`
Select the result list sort criteria and/or direction	Search	`resultsSort`	`resultsSortBy`

See Implement a Result List - Sorting Query Results.

Switching result list layouts

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Select the result list layout	Custom	`resultsLayout`	`changeResultsLayout`	`resultsLayoutChangeTo`

See Implement a Result List - Switching Result List Layouts.

Exporting query results

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Export the query results to an Excel document	Custom	`misc`	`exportToExcel`	N/A

See Implement a Result List - Exporting Results.

See Implement Facets.

See Implement Facets - Toggling Facet Values.

Action	Usage analytics event	`actionCause`	`customData`
Select a single value in a facet	Search	`facetSelect`	`facetField`, `facetId`, `facetTitle`, `facetValue`
Un-select a single value in a facet	Search	`facetDeselect`	`facetField`, `facetId`, `facetTitle`, `facetValue`
Exclude a single value in a facet	Search	`facetExclude`	`facetField`, `facetId`, `facetTitle`, `facetValue`
Un-exclude a single value in a facet	Search	`facetUnexclude`	`facetField`, `facetId`, `facetTitle`, `facetValue`
Reset selected/excluded values in a facet	Search	`facetClearAll`	`facetField`, `facetId`, `facetTitle`
Select a numeric value range in a facet	Search	`facetRangeSlider` / `facetRangeGraph`	`facetField`, `facetId`, `facetRangeStart`, `facetRangeEnd`
Select/un-select a single facet value by interacting with a query result	Search	`documentField`	`facetField`, `facetId`, `facetTitle`, `facetValue`
Un-select/un-exclude a single facet value by interacting with breadcrumbs	Search	`breadcrumbFacet`	`facetId`, `facetTitle`, `facetValue`
Clear all selected/excluded facet values by interacting with breadcrumbs	Search	`breadcrumbResetAll`	N/A

See Implement Facets - Toggling Facet Values.

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Change facet sort criteria / direction	Custom	`facet`	`facetUpdateSort`	`criteria`, `facetId`, `facetTitle`

See Implement Facets - Toggling Facet Values.

Action	Usage analytics event	`eventType`	`eventValue`	`customData`
Search for a value in a facet	Custom	`facet`	`facetSearch`	`facetId`, `facetTitle`

Action	Usage analytics event	`actionCause`	`customData`
Toggle a facet operator	Search	`facetToggle`	`facetId`, `facetOperatorBefore`, `facetOperatorAfter`

Custom filter actions

Action	Usage analytics event	`actionCause`	`customData`
Create, update, or interact with a custom filter	Search	`customfiltersChange`	`customFilterName`, `customFilterType`, `customFilterExpression`
Create or update an advanced search filter	Search	`advancedSearch`	N/A
Clear an advanced search filter by interacting with breadcrumbs	Search	`breadcrumbAdvancedSearch`	N/A

Standard actions and Usage Analytics reference

Standard actions and Usage Analytics reference