Actions

This is for:

Developer

This page lists the various Coveo Headless actions available in version 0.8.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 (for example, 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 (for example, 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 (for example, 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 (for example, https://connect.coveo.com/s/).

  • apiBaseUrl: (string) The Usage Analytics API base URL to use (for example, 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 (for example, mycoveoorganizationg8tp8wu3)

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

updateSearchConfiguration

Updates the search configuration.

Parameters:

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

  • pipeline: (string) The name of the query pipeline to use for the query (for example, 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 (for example, ExternalSearch).

Context Actions

addContext

Adds a new context value.

Parameters:

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

removeContext

Removes a context key-value pair.

Parameters:

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

setContext

Sets the query context.

Parameters:

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

Did-You-Mean Actions

applyDidYouMeanCorrection

Applies a did-you-mean correction.

Parameters:

  • correction: (string) The target correction (for example, "corrected string").

disableDidYouMean

Disables did-you-mean.

enableDidYouMean

Enables did-you-mean.

logDidYouMeanAutomatic

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

logDidYouMeanClick

Logs a did-you-mean click event, that is, when a user clicks 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 (for example, "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 (for example, "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 (for example, "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 (for example, "1").

  • numberOfValues: (number) The new number of facet values (for example, 10).

updateFacetSortCriterion

Updates the sort criterion of a facet.

Parameters:

  • facetId: (string) The unique identifier of the facet (for example, "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 (for example, "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 (that is, 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 (for example, "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 (for example, "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 (for example, "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 (for example, "1").

  • numberOfValues: (number) The new number of facet values (for example, 10).

updateCategoryFacetSortCriterion

Updates the sort criterion for the category facet

Parameters:

  • facetId: (string) The unique identifier of the facet (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, "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 (for example, ["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 (for example, 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 (for example, 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 (for example, 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 (for example, 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 (for example, b953ab2e-022b-4de4-903f-68b2c0682942).

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

  • count: (number) The number of query suggestions to request from Coveo ML (for example, 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 (for example, b953ab2e-022b-4de4-903f-68b2c0682942).

  • expression: (string) The selected query suggestion (for example, 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 (for example, 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