Standard actions and Usage Analytics reference

This is for:

Developer

This article lists some frequent actions that 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 (UA) event (search, click, or custom) that must be logged when this action is performed.

  • 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:

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

Important

You must ensure that user interactions with your custom search interface implementation log UA events in a way that resembles what the Coveo JavaScript Search Framework or the Atomic or Headless libraries would do in similar circumstances. Otherwise:

  • Standard UA reports may become incoherent in the underlying Coveo organization, especially if that organization powers Coveo JavaScript Search Framework, Atomic, or Headless search interfaces as well as custom search interfaces.

  • Coveo ML models may not function properly, or may require extensive customization.

Generic actions

This section lists the generic actions that you may want to make available in a custom search interface implementation.

Initialize a search interface

The following table lists the actions to use when initializing a search interface.

Action UA event actionCause customData

Load a standard search interface

Search

interfaceLoad

N/A

Load a recommendation interface

Search

recommendationInterfaceLoad

N/A

Select a tab

The following table lists the actions to use when selecting a tab. See Implement tabs.

Action UA event actionCause customData

Select a tab

Search

interfaceChange

interfaceChangeTo

Handle Coveo query pipeline triggers

The following table lists the actions to use when handling Coveo query pipeline triggers.

Action UA 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 user settings

The following table lists the actions to use when managing user settings.

Action UA event actionCause eventType eventValue customData

Update user preferences

Custom

N/A

preferences

preferencesChange

preferenceName, preferenceType

Resolve user geolocation

Search

positionSet

N/A

N/A

N/A

Handle query errors

The following table lists the actions to use when handling query errors.

Action UA 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

This section lists the search box actions that you may want to make available in a custom search interface implementation. See Implement a search box.

Submit user queries

The following table lists the actions to use when submitting user queries. See Implement a search box - Submit a query.

Action UA event actionCause customData

Send a user query from a non-standalone search box

Search

searchboxSubmit

N/A

Execute a user query sent from a standalone search box

Search

searchFromLink

N/A

Clear a non-standalone search box (and send a blank user query as a side effect)

Search

searchboxClear

N/A

Handle Coveo ML query suggestions

The following table lists the actions to use when handling Coveo ML query suggestions. See Implement a search box - Provide Coveo Machine Learning query suggestions.

Action UA event actionCause customData

Select a Coveo ML QS 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

Handle field-based query suggestions

The following table lists the actions to use when handling field-based QS. See Implement a search box - Provide field-based query completion suggestions.

Action UA event actionCause customData

Select a field-based suggestion

Search

omniboxField

N/A

Correct queries

The following table lists the actions to use when correcting queries. See Implement a search box - Correct queries.

Action UA event actionCause customData

Select a query correction suggestion

Search

didyoumeanClick

N/A

Trigger an automatically corrected query

Search

didyoumeanAutomatic

N/A

Result list actions

This section lists the result list actions that you may want to make available in a custom search interface implementation. See Implement a result list.

Open query results

The following table lists the actions to use when opening query results. See Implement a result list - Open query results.

Action UA event actionCause customData

Open a query result

Click

documentOpen

author, contentIdKey, contentIdValue, documentTitle, documentURL

Open a Coveo ML Content Recommendation (CR) result in a recommendation interface

Click

recommendationOpen

author, documentTitle, documentURL

Preview a query result

Click

documentQuickview

author, contentIdKey, contentIdValue, documentTitle, documentURL

Page query results

The following table lists the actions to use when paging query results. See Implement a result list - Page query results.

Action UA 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

Sort query results

The following table lists the actions to use when sorting query results. See Implement a result list - Sort query results.

Action UA event actionCause customData

Select the result list sort criteria or direction

Search

resultsSort

resultsSortBy

Switch result list layouts

The following table lists the actions to use when switching result list layouts. See Implement a result list - Switch result list layouts.

Action UA event eventType eventValue customData

Select the result list layout

Custom

resultsLayout

changeResultsLayout

resultsLayoutChangeTo

Export query results

The following table lists the actions to use when exporting query results. See Implement a result list - Export results.

Action UA event eventType eventValue customData

Export the query results to an Excel document

Custom

misc

exportToExcel

N/A

Facet actions

This section lists the facet actions that you may want to make available in a custom search interface implementation. See Implement facets.

Toggle facet values

The following table lists the actions to use when toggling facet values. See Implement facets - Toggle facet values.

Action UA 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 and 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 or un-select a single facet value by interacting with a query result

Search

documentField

facetField, facetId, facetTitle, facetValue

Un-select or 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

Sort facet values

The following table lists the actions to use when sorting facet values. See Implement facets.

Action UA event eventType eventValue customData

Change facet sort criteria or direction

Custom

facet

facetUpdateSort

criteria, facetId, facetTitle

The following table lists the actions to use when performing facet search. See Implement facets - Perform facet search.

Action UA event eventType eventValue customData

Search for a value in a facet

Custom

facet

facetSearch

facetId, facetTitle

Switch between conjunctive and disjunctive facet

The following table lists the actions to use when switching between a conjunctive and disjunctive facet.

Action UA event actionCause customData

Toggle a facet operator

Search

facetToggle

facetId, facetOperatorBefore, facetOperatorAfter

Custom filter actions

The following table lists the custom filter actions that you may want to make available in a custom search interface implementation.

Action UA event actionCause customData

Create, update, or interact with a custom search result filter

Search

customfiltersChange

customFilterName, customFilterType, customFilterExpression

Create or update an advanced search result filter

Search

advancedSearch

N/A

Clear an advanced search result filter by interacting with breadcrumbs

Search

breadcrumbAdvancedSearch

N/A