Recommendation engine

This is for:

Developer

In this article

Initialize
Related Types
Methods
Engine Controllers
Engine Actions

The engine for powering recommendation experiences.

Initialize

`buildRecommendationEngine`

Creates a recommendation engine instance.

Parameters

options: RecommendationEngineOptions

The recommendation engine options.

Returns RecommendationEngine

`RecommendationEngineOptions`

The recommendation engine options.

Properties

configuration: RecommendationEngineConfiguration

The recommendation engine configuration options.
loggerOptions?: LoggerOptions

The logger options.
middlewares?: Middleware<{}, State>[]

List of additional middlewares. A middleware is a higher-order function that composes a dispatch function to return a new dispatch function. It is useful for logging actions, performing side effects like routing, or turning an asynchronous API call into a series of synchronous actions.
navigatorContextProvider?: NavigatorContextProvider

An optional function returning navigation context. (referer, location, UserAgent)
preloadedState?: State

The initial headless state. You may optionally specify it to hydrate the state from the server in universal apps, or to restore a previously serialized user session.

`RecommendationEngineConfiguration`

The recommendation engine configuration options.

Properties

locale?: string

The locale of the current user. Must comply with IETF’s BCP 47 definition: https://www.rfc-editor.org/rfc/bcp/bcp47.txt.

Notes: Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.
pipeline?: string

Specifies the name of the query pipeline to use for the query. If not specified, the default query pipeline will be used.
preprocessSearchResponseMiddleware?: PostprocessSearchResponseMiddleware

Allows for augmenting a search response before the state is updated.
proxyBaseUrl?: string

The base URL to use to proxy Coveo search requests (e.g., https://example.com/search).

This is an advanced option that you should only set if you need to proxy Coveo search requests through your own server. In most cases, you should not set this option.

By default, no proxy is used and the Coveo Search API requests are sent directly to the Coveo platform through the search organization endpoint resolved from the organizationId and environment values provided in your engine configuration (i.e., https://<organizationId>.org.coveo.com or https://<organizationId>.org<environment>.coveo.com, if the environment values is specified and different from prod).

If you set this option, you must also implement the following proxy endpoints on your server, otherwise the recommendation engine will not work properly:
- POST / to proxy requests to POST https://<organizationId>.org<environment|>.coveo.com/rest/search/v2 - POST /plan to proxy requests to POST https://<organizationId>.org<environment|>.coveo.com/rest/search/v2/plan - POST /querySuggest to proxy requests to POST https://<organizationId>.org<environment|>.coveo.com/rest/search/v2/querySuggest - POST /facet to proxy requests to POST https://<organizationId>.org<environment|>.coveo.com/rest/search/v2/facet - POST /html to proxy requests to POST https://<organizationId>.org<environment|>.coveo.com/rest/search/v2/html - GET /fields to proxy requests to GET https://<organizationId>.org<environment|>.coveo.com/rest/search/v2/fields
searchHub?: string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates. Coveo Machine Learning models use this information to provide contextually relevant output. Notes: This parameter will be overridden if the search request is authenticated by a search token that enforces a specific searchHub. When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.
timezone?: string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression, facets, and result items. By default, the timezone will be guessed.
accessToken: string

The access token to use to authenticate requests against the Coveo Cloud 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 Cloud organization.
organizationId: string

The unique identifier of the target Coveo Cloud organization (e.g., mycoveocloudorganizationg8tp8wu3)
analytics?: AnalyticsConfiguration

Allows configuring options related to analytics.
environment?: PlatformCombination['env']

The environment in which the organization is hosted.

The dev and stg environments are only available internally for Coveo employees (e.g., Professional Services).

Defaults to prod.
name?: string

The Engine name (e.g., myEngine). Specifying your Engine name will help in debugging when using an application with multiple Redux stores.

Default: 'coveo-headless'
preprocessRequest?: PreprocessRequest

Allows for augmenting a Platform request before it is sent.
renewAccessToken?: () => 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).

`LoggerOptions`

The logger options.

Properties

level?: LevelWithSilent

By default, is set to warn.
logFormatter?: (object: {}) => {}

Changes the shape of the log object. This function will be called every time one of the log methods (such as .info) is called. All arguments passed to the log method, except the message, will be pass to this function. By default it does not change the shape of the log object.

`Middleware<{}, State>[]`

List of additional middlewares. A middleware is a higher-order function that composes a dispatch function to return a new dispatch function. It is useful for logging actions, performing side effects like routing, or turning an asynchronous API call into a series of synchronous actions.

Properties

(call): (api: MiddlewareAPI<D, S>): (next: (action: unknown) => unknown) => (action: unknown) => unknown;

`AnalyticsConfiguration`

Allows configuring options related to analytics.

Properties

analyticsClientMiddleware?: AnalyticsClientSendEventHook

analyticsClientMiddleware allows to hook into an analytics event payload before it is sent to the Coveo platform.
analyticsMode?: 'legacy' | 'next'

The analytics client to use. - legacy: The legacy analytics client, i.e., the Coveo Analytics.js library. - next: The next analytics client, i.e., the Coveo Event Protocol with the Relay library.

The default value is next.
anonymous?: boolean

Whether analytics events should be logged anonymously. If set to true, the Usage Analytics Write API will not extract the name and userDisplayName, if present, from the search token
deviceId?: string

The name of the device that the end user is using. It should be explicitly configured in the context of a native mobile app.
documentLocation?: string

Specifies the URL of the current page or component.
enabled?: boolean

Specifies if usage analytics tracking should be enabled.

By default, all analytics events will be logged.
originContext?: string

Sets the Origin Context dimension on the analytics events.

You can use this dimension to specify the context of your application. The possible values are "Search", "InternalSearch", and "CommunitySearch".

The default value is Search.
originLevel2?: string

Sets the value of the Origin Level 2 dimension on the analytics events.

Origin level 2 is a usage analytics event metadata whose value should typically be the name/identifier of the tab from which the usage analytics event originates.

In the context of product listing, the value should match the breadcrumb of the product listing page from which the usage analytics event originates (for example, canoes-kayaks/kayaks/sea-kayaks).

When logging a usage analytics event, originLevel2 should always be set to the same value as the corresponding tab (parameter) Search API query parameter so Coveo Machine Learning models function properly, and usage analytics reports and dashboards are coherent.

If left unspecified, this value will automatically try to resolve itself from the tab Search API query parameter.
originLevel3?: string

Origin level 3 is a 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.

When logging a Search usage analytics event, originLevel3 should always be set to the same value as the corresponding referrer Search API query parameter so usage analytics reports and dashboards are coherent.

This value is optional, and will automatically try to resolve itself from the referrer search parameter.
proxyBaseUrl?: string

The base URL to use to proxy Coveo analytics requests (e.g., https://example.com/analytics).

This is an advanced option that you should only set if you need to proxy Coveo analytics requests through your own server. In most cases, you should not set this option.

By default, no proxy is used and the Coveo analytics requests are sent directly to the Coveo platform through the analytics organization endpoint resolved from the organizationId and environment values provided in your engine configuration (i.e., https://<organizationId>.analytics.org.coveo.com or https://<organizationId>.analytics.org<environment>.coveo.com, if the environment values is specified and different from prod).

If you set this option, you must also implement the correct proxy endpoints on your server, depending on the analyticsMode you are using.

If you are using the next analytics mode, you must implement the following proxy endpoints:
- POST / to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/organizations/{organizationId}/events/v1 - POST /validate to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/organizations/{organizationId}/events/v1/validate
  
  The Event Protocol Reference provides documentation on the analytics event schemas that can be passed as request bodies to the above endpoints.
  
  If your are using the legacy analytics mode, your proxyBaseUrl must end with /rest/v15/analytics, and you must implement the following proxy endpoints:
- POST /click to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/click - POST /collect to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/collect - POST /custom to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/custom - GET /monitoring/health to proxy requests to GET https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/monitoring/health - POST /search to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/search - POST /searches to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/searches - GET /status to proxy requests to GET https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/status - POST /view to proxy requests to POST https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/view - DELETE /visit to proxy requests to DELETE https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/visit - GET /visit to proxy requests to GET https://<organizationId>.analytics.org<environment|>.coveo.com/rest/v15/analytics/visit
runtimeEnvironment?: IRuntimeEnvironment

Optional analytics runtime environment, this is needed for analytics to work correctly if you’re running outside of a browser. See https://github.com/coveo/coveo.analytics.js for more info.
trackingId?: string

The unique identifier of the tracking target.
userDisplayName?: string

Specifies the user display name for the usage analytics logs.

`Unsubscribe`

Call signatures

(): void;

Methods

`addReducers`

Adds the specified reducers to the store.

Parameters

reducers: ReducersMapObject

An object containing the reducers to attach to the engine.

`disableAnalytics`

Disable analytics tracking

`enableAnalytics`

Enable analytics tracking

`subscribe`

Adds a change listener. It will be called any time an action is dispatched, and some part of the state tree may potentially have changed. You may then access the new state.

Parameters