Commerce engine

This is for:

Developer
Important

The Headless commerce engine, controllers, and actions are in open beta and therefore under active development. Reach out to your Coveo team for support in adopting them.

The engine for powering commerce experiences.

In Open Beta. Reach out to your Coveo team for support in adopting this.

Initialize

buildCommerceEngine

Creates a commerce engine instance.

In Open Beta. Reach out to your Coveo team for support in adopting this.

Parameters

Returns CommerceEngine

CommerceEngineOptions

The commerce engine options.

Properties

  • configuration: CommerceEngineConfiguration

    The commerce 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.

CommerceEngineConfiguration

The commerce engine configuration options.

Properties

  • context: ContextOptions

  • cart?: CartInitialState

  • environment?: PlatformCombination['env']

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

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

  • organizationEndpoints?: OrganizationEndpoints

    The endpoints to use.

    The getOrganizationEndpoints helper function can be useful to create the appropriate object.

    We recommend using this option, since it has resiliency benefits and simplifies the overall configuration for multi-region deployments. See Organization endpoints.

  • platformUrl?: string

    The Platform URL to use. (e.g., https://platform.cloud.coveo.com) The platformUrl() helper method can be useful to know what url is available.

  • 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

  • browserPostLogHook?: (level: LogLevel, logEvent: LogEvent) => void

    Function which will be called after writing the log message in the browser.

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

ContextOptions

Properties

  • country: string

  • currency: CurrencyCodeISO4217

  • language: string

  • view: View

  • user?: { userAgent?: string; }

CartInitialState

Properties

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.

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

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

  • userDisplayName?: string

    Specifies the user display name for the usage analytics logs.

View

Properties

  • url: string

  • referrer?: string

CartItemWithMetadata[]

Properties

  • name: string

    The name of the cart item.

  • price: number

    The price of the cart item.

  • productId: string

    The unique identifier of the product.

  • quantity: number

    The quantity of the product in the cart.

Methods

executeFirstSearch

Executes the first search.

executeFirstSearchAfterStandaloneSearchBoxRedirect

Executes the first search after a redirection from a standalone search box.