@coveo/headless
    Preparing search index...

    Interface AnalyticsConfiguration

    The analytics configuration options.

    interface AnalyticsConfiguration {
        analyticsClientMiddleware?: AnalyticsClientSendEventHook;
        analyticsMode?: "legacy" | "next";
        anonymous?: boolean;
        deviceId?: string;
        disableBrowserPrivacySignals?: boolean;
        documentLocation?: string;
        enabled?: boolean;
        originContext?: string;
        originLevel2?: string;
        originLevel3?: string;
        proxyBaseUrl?: string;
        runtimeEnvironment?: IRuntimeEnvironment;
        source?: Partial<Record<"@coveo/atomic" | "@coveo/quantic", string>>;
        trackingId?: string;
        userDisplayName?: string;
    }
    Index
    analyticsClientMiddleware? analyticsMode? anonymous? deviceId? disableBrowserPrivacySignals? documentLocation? enabled? originContext? originLevel2? originLevel3? proxyBaseUrl? runtimeEnvironment? source? trackingId? userDisplayName?
    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, that is, the Coveo Analytics.js library.
    • next: The next analytics client, that is, the Coveo Event Protocol with the Relay library.

    The default value is next.

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

    disableBrowserPrivacySignals?: boolean

    Whether to stop honoring browser privacy signals — Do Not Track (DNT) and Global Privacy Control (GPC) — when deciding whether to send legacy analytics (analyticsMode: 'legacy').

    By default (false), Coveo libraries honor these signals: when the browser presents DNT or GPC, legacy analytics is automatically disabled. Setting this option to true is a deliberate choice that you configure in your own application code; legacy analytics events are then sent even when the browser presents a DNT or GPC signal.

    Coveo honors these signals by default and cannot determine whether overriding them is appropriate for your use case. If you enable this option, you are responsible for ensuring that doing so complies with the privacy laws and obligations that apply to you. Note that GPC is legally recognized as a valid opt-out mechanism in some jurisdictions (for example, under the California Consumer Privacy Act (CCPA) as amended by the California Privacy Rights Act (CPRA)).

    This option:

    • applies only when analyticsMode is explicitly set to 'legacy';
    • has no effect with analyticsMode: 'next', which does not honor these signals;
    • does not override an explicit enabled: false or a runtime disableAnalytics() call, which always disable analytics.

    Introduced as deprecated on purpose to signal that it is transitional. This option exists only to bridge legacy-analytics deployments where a browser privacy signal is enforced by policy, and it will be removed when legacy analytics is removed (see KIT-2844). Migrate to Event Protocol (analyticsMode: 'next') rather than relying on this option long term.

    false

    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 (for example, https://example.com/analytics).

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

    See Headless proxy: Analytics.

    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.

    source?: Partial<Record<"@coveo/atomic" | "@coveo/quantic", string>>

    Specifies the frameworks and version used around Headless (e.g. @coveo/atomic).

    trackingId?: string

    The unique identifier of the tracking target.

    userDisplayName?: string

    Specifies the user display name for the usage analytics logs.

    Settings
    Member Visibility
    In this article
    Properties