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 behaviour after deployment.

Supported browsers

The SDK supports the following browsers:

Chrome (last two versions)
Firefox (last two versions)
Safari (last two 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 Engagement JavaScript SDK

The Bloomreach Web SDK and the Engagement 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 Engagement JavaScript SDK, you must fully replace the existing snippet before the new one goes live. See Migrate from Engagement JS SDK for the full migration process.

Event schema and data sharing

Events must follow the prescribed schema to reach Discovery

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

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

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

Engagement and Discovery use different visitor IDs

Engagement and Discovery currently maintain separate visitor ID cookies. When you connect a new destination for an existing visitor, that destination doesn't recognise 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 behaviour.
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

Discovery SEO standalone trackers: Some Discovery SEO implementations require additional standalone Discovery trackers alongside the Web SDK. This depends on your specific Discovery 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 Engagement JavaScript SDK. All existing Engagement JavaScript SDK limitations for web personalization also apply to the Bloomreach Web SDK.