Standard actions and Usage Analytics reference
Standard actions and Usage Analytics reference
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) oreventType
andeventValue
(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 |
Search box actions
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
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.
Facet actions
See Implement Facets.
Toggling facet values
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 |
Sorting facet values
See Implement Facets - Toggling Facet Values.
Action | Usage analytics event | eventType |
eventValue |
customData |
---|---|---|---|---|
Change facet sort criteria / direction | Custom | facet |
facetUpdateSort |
criteria , facetId , facetTitle
|
Performing facet search
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
|
Switching between conjunctive and disjunctive facet
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 |