HomeEngagementContentDiscoveryOther resources
Guides

Cookie tracking modes

Suggest Edits

Bloomreach uses tracking cookies in several modes, depending on your setup and instance. The flow in cookie exchange differs when using Experiments or not.

The following tracking modes are supported:

Cookie flow

In JS SDK, there are generally two HTTP requests which set up the tracking cookie:

  • /bulk request, performed by the SDK when initialized.
  • /webxp/.../modifications/min.js request, performed by the integration snippet when the page starts loading. This request can only be made if Experiments are enabled.

Default

This is the default mode if you don't change the project configuration.

In this mode, two tracking cookies are used:

  • JS SDK sets the __exponea_etc__ tracking cookie in the browser using JavaScript. The value for this cookie is retrieved from async-api using the system/ids command in the /bulk request. The SDK makes this request when it is initialized.
    • This is a first-party cookie with the domain set to the website's domain.
  • xnpe_<project-id> backend cookie is set by async-api or webxp-api, depending on whether you have Experiments enabled.
    • This is a third-party cookie with its domain set to api.exponea.com (or the instance tracking domain). It is included in every HTTP request made by the browser to that domain.

The expiration dates of both cookies are set based on the setting in the SDK's configuration. Read more about Cookies options.

On each webpage load, two cookie-related HTTP requests are made by the SDK:

  1. If you have Experiments enabled, the SDK makes a request for /webxp/.../modifications.min.js.
    1. If the SDK has the __exponea_etc__ tracking cookie, it will include its value in the URL of the request.
    2. If the expiration date is set in the SDK's configuration, it will be included in the request's URL.
    3. After receiving the request for modifications, webxp-api either:
      1. Generates a new cookie value, or
      2. Uses the one provided in the URL or the HTTP request and sets the xnpe_<project-id> cookie in the HTTP response. It will use the provided expiration date in the URL, or the default of 3 years, for the cookie.
  2. SDK makes a /bulk request containing a system/ids command.
    1. SDK includes all customer IDs it has in the command data, including the __exponea_etc__ cookie. The SDK also includes the expiration date set in the configuration.
    2. After receiving the system/ids command, async-api either:
      1. Generates a new cookie value, or
      2. Uses the one provided in the command data or the HTTP request and sets the xnpe_<project-id> cookie in the HTTP response. It then returns the cookie value as a response to the command. It will use the provided expiration date in the command data, or the default of 3 years, for the HTTP cookie.

📘

Note

xnpe_<project-id> is set in the response every time, even if the cookie already exists and is included in the HTTP request by the browser.

This is to ensure that the cookie always has the expiration date configured in the SDK.

Shared cookies

Some websites cross multiple domains and want to share identity across all connected websites. They want to track all websites connected in various domains for a single project in Bloomreach.

This mode uses two tracking cookies:

  • Similar to the Default mode, the JS SDK uses its __exponea_etc__ tracking cookie.
  • __EX__<group-id>__ backend cookie is either set by async-api or webxp-api. This depends on whether you have Experiments enabled. <group-id> is the ID of the shared cookie group with multiple projects, defined in the Bloomreach Engagement app administration interface.
    • This is a third-party cookie with its domain set to api.exponea.com (or the instance tracking domain). It is included in every HTTP request made by the browser to that domain.

The expiration dates of both cookies are set based on the setting in the SDK's configuration. Read more about Cookies options.

🚧

Not a recommended practice

Shared cookies are widely affected by browser privacy policies (like Intelligent Tracking Prevention). For this reason, the use of this feature is discouraged.

Regarding HTTP requests, the SDK makes the same requests as the Default mode. The SDK is unaware that Shared cookies might be enabled.

The only difference is that the APIs respond with the __EX__<group-id>__ cookie instead of the xnpe__<project-id> cookie.

Custom tracking domain

The Custom tracking domain makes Bloomreach Engagement compatible with browsers' privacy policies, but it also helps to deal with ad blockers that block common known "trackers" (such as the api.exponea.com domain).

In terms of HTTP requests and cookie flow, the SDK and the APIs behave the same way as in the Default mode. The SDK isn't aware of this feature (as of 2021-5-21); it makes the same requests and receives the same cookies from the APIs.

The only difference is that the domain of the xnpe<project-id> cookie will be the one configured in the Custom tracking domain interface in the Bloomreach Engagement. The JS SDK will also have this custom domain set as its target and will make requests to it.

This turns the xnpe_<project-id> cookie from a third-party cookie to a first-party cookie.

Private tracking domain

If you have a private instance of Bloomreach Engagement, the instance is set up to have its own tracking domain.

With a private tracking domain, you can decide to use any of the other cookie modes: Default, Shared cookies, or Custom tracking domain.

Updated about 15 hours ago