Actions

Coveo Relevance Cloud Developer Headless Product Documentation

This page lists the various Coveo Headless actions available in version 0.1.0

Analytics Actions

logInterfaceChange

Logs an interface change event.

logInterfaceLoad

Logs an interface load event.

logClickEvent

Logs a click event.

logCustomEvent

Logs a custom event.

logSearchEvent

Logs a search event.

Configuration Actions

disableAnalytics

Disables analytics tracking.

enableAnalytics

Enables analytics tracking.

renewAccessToken

Renews the accessToken specified in the global headless engine configuration.

Parameters:

  • renew: (() ⇒ Promise<string>) A function that fetches a new access token. The function must return a Promise that resolves to a string (the new access token).

setOriginLevel2

Sets originLevel2 for analytics tracking.

Parameters:

  • originLevel2: (string) The origin level 2 usage analytics event metadata whose value should typically be the identifier of the tab (e.g., All).

setOriginLevel3

Sets originLevel3 for analytics tracking.

Parameters:

  • originLevel3: (string) The origin level 3 usage analytics event metadata whose value should typically be the URL of the page that linked to the search interface (e.g., https://connect.coveo.com/s/).

updateAnalyticsConfiguration

Updates the analytics configuration.

Parameters:

  • enabled: (boolean) Whether to enable usage analytics tracking.

  • originLevel2: (string) The origin level 2 usage analytics event metadata whose value should typically be the identifier of the tab from which the usage analytics event originates (e.g., All).

  • originLevel3: (string) The origin level 3 usage analytics event metadata whose value should typically be the URL of the page that linked to the search interface that’s making the request (e.g., https://connect.coveo.com/s/).

  • apiBaseUrl: (string) The Usage Analytics API base URL to use (e.g., https://analytics.cloud.coveo.com/rest/ua).

  • runtimeEnvironment: (IRuntimeEnvironment) The Coveo analytics runtime to use, see https://github.com/coveo/coveo.analytics.js for more info.

updateBasicConfiguration

Updates the global headless engine configuration.

Parameters:

  • accessToken: (string) The access token to use to authenticate requests against Coveo endpoints. Typically, this will be an API key or search token that grants the privileges to execute queries and push usage analytics data in the target Coveo organization.

  • organizationId: (string) The unique identifier of the target Coveo organization (e.g., mycoveoorganizationg8tp8wu3)

  • platformUrl: (string) The Plaform URL to use (e.g., https://platform.cloud.coveo.com).

updateSearchConfiguration

Updates the search configuration.

Parameters:

  • apiBaseUrl: (string) The Search API base URL to use (e.g., https://platform.cloud.coveo.com/rest/search/v2).

  • pipeline: (string) The name of the query pipeline to use for the query (e.g., External Search). If not specified, the default query pipeline will be used.

  • searchHub: (string) The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates (e.g., ExternalSearch).

Context Actions

addContext

Adds a new context value.

Parameters:

  • payload: ({contextKey: string; contextValue: ContextValue}) The key-value pair to add to the context (e.g., {contextKey: "age", contextValue: "18-35"}).

removeContext

Removes a context key-value pair.

Parameters:

  • key: (string) The key to remove from the context (e.g., "age").

setContext

Sets the query context.

Parameters:

  • payload: (Context) The new context (e.g., {age: "18-35"}).

Did-You-Mean Actions

applyDidYouMeanCorrection

Applies a did-you-mean correction.

Parameters:

  • correction: (string) The target correction (e.g., "corrected string").

disableDidYouMean

Disables did-you-mean.

enableDidYouMean

Enables did-you-mean.

logDidYouMeanAutomatic

Logs a did-you-mean automatic event, i.e., when the interface automatically selects a did-you-mean suggestion.

logDidYouMeanClick

Logs a did-you-mean click event, i.e., when a user clicks on a did-you-mean suggestion.

Facet Actions

Generic Facet Actions

deselectAllFacetValues

Deselects all values of a facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

registerFacet

Registers a facet in the facet set.

Parameters:

  • (FacetRegistrationOptions): The options to register the facet with.

toggleSelectFacetValue

Toggles a facet value.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (FacetValue) The target facet value.

updateFacetIsFieldExpanded

Whether to expand (show more values than initially configured) or shrink down the facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • isFieldExpanded: (boolean) Whether to expand or shrink down the facet.

updateFacetNumberOfValues

Updates the number of values of a facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • numberOfValues: (number) The new number of facet values (e.g., 10).

updateFacetSortCriterion

Updates the sort criterion of a facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • criterion: (FacetSortCriterion) The criterion by which to sort the facet.

logFacetClearAll

Logs a facet clear all event.

logFacetDeselect

Logs a facet deselect event.

logFacetSearch

Logs a facet search event.

logFacetSelect

Logs a facet value selection event.

logFacetShowLess

Logs a facet show less event.

logFacetShowMore

Logs a facet show more event.

logFacetUpdateSort

Logs a facet sort event.

buildFacetBaseMetadata

buildFacetSelectionChangeMetadata

buildFacetStateMetadata

getStateNeededForFacetMetadata

executeToggleFacetSelect

Toggles the facet value and then executes a search with the appropriate analytics tag.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (FacetValue) The target facet value.

Facet Search Actions

registerCategoryFacetSearch

Registers a category facet search box with the specified options.

Parameters:

  • (FacetSearchOptions): An object specifying the target facet and facet search box options.

selectCategoryFacetSearchResult

Selects the corresponding category facet value for the provided category facet search result

executeFacetSearch

Executes a facet search (i.e., a search for facet values in a facet search box).

Parameters:

  • facetId: (string) The unique identifier of the facet for which to perform a facet search (e.g., "1").

registerFacetSearch

Registers a facet search box with the specified options.

Parameters:

  • (FacetSearchOptions): An object specifying the target facet and facet search box options.

selectFacetSearchResult

Selects a facet search result.

Parameters:

  • (selectFacetSearchResultPayload): An object that specifies the target facet and facet search result.

updateFacetSearch

Updates the options of a facet search box.

Parameters:

  • (FacetSearchOptions): An object specifying the target facet and facet search box options.

Category Facet Actions

deselectAllCategoryFacetValues

Deselects all values of a category facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

registerCategoryFacet

Registers a category facet in the category facet set.

Parameters:

  • (CategoryFacetRegistrationOptions): The options to register the category facet with.

toggleSelectCategoryFacetValue

Toggles a category facet value.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (CategoryFacetValue) The target category facet value.

updateCategoryFacetNumberOfValues

Updates the number of values of a category facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • numberOfValues: (number) The new number of facet values (e.g., 10).

updateCategoryFacetSortCriterion

Updates the sort criterion for the category facet

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • criterion: (FacetSortCriterion) The criterion by which to sort the facet.

executeDeselectAllCategoryFacetValues

Deselects the all values on the path to the currently selected category facet value and executes a search with the appropriate analytics

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • numberOfValues: (number) The number of category facet values to show after deselecting.

executeToggleCategoryFacetSelect

Toggles the facet value and then executes a search with the appropriate analytics tag.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (CategoryFacetValue) The target facet value.

Range Facet Actions

deselectAllDateFacetValues

Deselects all values of a date facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

registerDateFacet

Registers a date facet.

Parameters:

  • (DateFacetRegistrationOptions): The options to register the facet with.

toggleSelectDateFacetValue

Toggles a date facet value.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (DateFacetValue) The target date facet value.

updateDateFacetSortCriterion

Updates the sort criterion of a date facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • criterion: (RangeFacetSortCriterion) The target criterion.

executeToggleDateFacetSelect

Toggles the date facet value and then executes a search with the appropriate analytics tag.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (DateFacetValue) The target date facet value.

updateRangeFacetSortCriterion

Updates the sort criterion of a range facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • criterion: (RangeFacetSortCriterion) The target criterion.

executeToggleRangeFacetSelect

Executes a search with the appropriate analytics for a toggle range facet value

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (RangeFacetValue) The target range facet value.

deselectAllNumericFacetValues

Deselects all values of a numeric facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

registerNumericFacet

Registers a numeric facet.

Parameters:

  • (NumericFacetRegistrationOptions): The options to register the facet with.

toggleSelectNumericFacetValue

Toggles a numeric facet value.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (NumericFacetValue) The target numeric facet value.

updateNumericFacetSortCriterion

Updates the sort criterion of a numeric facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • criterion: (RangeFacetSortCriterion) The target criterion.

executeToggleNumericFacetSelect

Toggles the numeric facet value and then executes a search with the appropriate analytics tag.

Parameters:

  • facetId: (string) The unique identifier of the facet (e.g., "1").

  • selection: (NumericFacetValue) The target numeric facet value.

Field Actions

registerFieldsToInclude

Registers the fields to include in the query response.

Parameters:

  • payload: (string[]) The target fields (e.g., ["field1", "field2"]).

History Actions

back

Moves backward in the interface history.

change

Updates the interface state as per the current step in the interface history.

forward

Moves forward in the interface history.

snapshot

Creates a snapshot of the current request parameters and adds it to the interface history.

Parameters:

  • (SearchParametersState): The current state of the search parameters.

logNavigateBackward

Logs an event which represents a move backward in the interface history.

logNavigateForward

Logs an event which represents a move forward in the interface history.

Pagination Actions

nextPage

Updates the page to the next page.

previousPage

Updates the page to the previous page.

registerNumberOfResults

Initializes the numberOfResults query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (number) The initial number of results.

registerPage

Sets the initial page by initializing the firstResult query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (number) The initial page number.

updateNumberOfResults

Updates the numberOfResults query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (number) The new number of results.

updatePage

Updates the page by updating the firstResult query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (number) The new page number.

logPageNext

Log pager next

logPageNumber

Log page number

logPagePrevious

Log pager previous

logPagerResize

Log pager resize

Pipeline Actions

setPipeline

Sets the query pipeline.

Parameters:

  • payload: (string) The query pipeline to set (may be empty).

Query Actions

updateQuery

Updates the basic query expression.

Parameters:

  • q: (string) The new basic query expression (e.g., acme tornado seeds).

logSearchboxSubmit

Log searchbox submit

Query Set Actions

registerQuerySetQuery

Registers a query in the query set.

Parameters:

  • id: (string) The unique identifier of the target query.

  • query: (string) The initial basic query expression.

updateQuerySetQuery

Updates a query in the query set.

Parameters:

  • id: (string) The unique identifier of the target query.

  • query: (string) The new basic query expression.

Query Suggest Actions

clearQuerySuggest

Clears the current partial basic query expression and the list of query suggestions in a specific query suggest entity.

Parameters:

  • id: (string) The unique identifier of the target query suggest entity (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

clearQuerySuggestCompletions

Clears the list of query suggestions in a specific query suggest entity.

Parameters:

  • id: (string) The unique identifier of the target query suggest entity (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

fetchQuerySuggestions

Fetches a list of query suggestions for a specific query suggest entity according to the current headless state.

Parameters:

  • id: (string) The unique identifier of the target query suggest entity (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

registerQuerySuggest

Registers a new query suggest entity to the headless state to enable the Coveo ML query suggestions feature.

Parameters:

  • id: (string) A unique identifier for the new query suggest entity (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

  • q: (string) The partial basic query expression for which to request query suggestions (e.g., cov).

  • count: (number) The number of query suggestions to request from Coveo ML (e.g., 3). Default: 5.

selectQuerySuggestion

Selects a suggestion provided through a specific query suggest entity.

Parameters:

  • id: (string) The unique identifier of the target query suggest entity (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

  • expression: (string) The selected query suggestion (e.g., coveo).

unregisterQuerySuggest

Unregisters an existing query suggest entity from the headless state.

Parameters:

  • id: (string) The unique identifier of the query suggest entity to unregister (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

buildQuerySuggestRequest

logQuerySuggestionClick

Redirection Actions

checkForRedirection

Preprocesses the query for the current headless state, and updates the redirection URL if a redirect trigger was fired in the query pipeline.

Parameters:

  • defaultRedirectionUrl: (string) The default URL to which to redirect the user.

buildPlanRequest

logTriggerRedirect

Log trigger redirection

Result Analytics Actions

logDocumentOpen

Logs a click event with an actionCause value of documentOpen.

Search Actions

executeSearch

Executes a search query.

Parameters:

  • analyticsAction: (SearchAction) The analytics action to log after a successful query.

fetchMoreResults

buildSearchRequest

logFetchMoreResults

logQueryError

Search Hub Actions

setSearchHub

Sets the search hub.

Parameters:

  • payload: (string) The new search hub (may be empty).

Sort Criteria Actions

registerSortCriterion

Initializes the sortCriteria query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (SortCriterion) The initial sort criterion.

updateSortCriterion

Updates the sortCriteria query parameter. For more information, refer to the documentation on query parameters.

Parameters:

  • payload: (SortCriterion) The sort criterion to set.

logResultsSort

Log results sort