Web SDK usage and limitations

This page covers the constraints and known limitations of the Bloomreach Web SDK. Review it before you start your implementation to avoid common issues, and refer back to it if you encounter unexpected behavior after deployment.

Supported browsers

The SDK supports the following browsers:

Chrome (last 2 versions)
Firefox (last 2 versions)
Safari (last 2 versions)
Opera (last version)

Installation constraints

One snippet per page

Install only one Bloomreach Web SDK snippet per page. The SDK doesn't support multiple running instances on the same page.

Can't run alongside the Marketing JavaScript SDK

The Bloomreach Web SDK and the Marketing JavaScript SDK share the same namespace and cookie structure. Running both simultaneously causes cookie collisions, which leads to lost visitor identification and corrupted tracking data.

If you're migrating from the Marketing JavaScript SDK, you must fully replace the existing snippet before the new one goes live. See Migrate from Marketing JS SDK for the full migration process.

Event schema and data sharing

Events must follow the prescribed schema to reach Search

You can track any event to Marketing. However, only events that follow the schema prescribed by Bloomreach or your implementation partner are forwarded to Search. Custom Marketing-only events are allowed, but they stay within Marketing and aren't shared with Search.

Pay close attention to the event schema your Bloomreach consultant or implementation partner provides. Events and event properties shared between Marketing and Search must match the prescribed names and structures exactly. Events that don't conform are accepted by Marketing but silently dropped by Search.

For the full list of required event names and properties, see Required events.

Marketing and Search use different visitor IDs

Marketing and Search currently maintain separate visitor ID cookies. When you connect a new destination for an existing visitor, that destination doesn't recognize them as a returning visitor immediately. There is a transition period after a new destination is connected during which returning visitors may be treated as new visitors by that destination.

Performance

The SDK loads in two parts. The inline snippet is approximately 3 KB and loads synchronously in the <head>. The full SDK library (brweb.min.js) is approximately 170 KB uncompressed (60 KB transferred after compression) and loads asynchronously.

If the SDK's load time is a concern for your website's performance, consider the following:

Set up a custom tracking domain (CTD) to serve the SDK from your own domain. This can improve load performance by reducing DNS lookup overhead and improving cache behavior.
Use server-side tracking for high-volume or performance-sensitive pages. See Server-side tracking for details.

Privacy and security

Don't add the tracking snippet to pages that handle sensitive information, such as payment gateways or checkout pages that display credit card data. Tracking scripts on these pages can be exploited to intercept sensitive financial information.

For data that should not pass through the browser, such as order costs, margins, or other commercially sensitive attributes, use server-side tracking instead of the Web SDK. See Server-side tracking.

Other limitations

Search SEO standalone trackers: Some Search SEO implementations require additional standalone Search trackers in addition to the Web SDK. This depends on your specific Search SEO configuration. Consult your Bloomreach representative to confirm whether this applies to your setup.
Cookie expiration and browser policy: The SDK sets cookie expiration based on your configuration. However, the visitor's browser cookie policy may cause cookies to expire sooner than the configured maximum, particularly for client-side cookies in Safari and other browsers with Intelligent Tracking Prevention (ITP). For more on cookie configuration, see Cookie expiration.
Web personalization: Web personalization features work the same way as in the Marketing JavaScript SDK. All existing Marketing JavaScript SDK limitations for web personalization also apply to the Bloomreach Web SDK.