Migrate from Engagement JS SDK tracking

This guide walks you through migrating from the Engagement JavaScript SDK to the Bloomreach Web SDK. Follow these steps if your website currently uses the Engagement JavaScript SDK (exponea) and you're moving to the unified Data hub tracking approach.

Before you start

SDK compatibility

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. You must fully replace the Engagement JavaScript SDK snippet before the new snippet goes live.

For more detail on this and other constraints, see Web SDK usage and limitations.

Changes in credentials

The Engagement JavaScript SDK uses a project token to identify your Engagement project. The Bloomreach Web SDK uses a stream_id from an Event stream instead. Get your stream_id from Data hub before you start.

Find your stream_id in Data Hub > Event streams > select your stream > Access security. See Find your credentials for the full walkthrough.

Choose your migration path

The steps in this guide depend on what you're migrating to:

In all cases, the steps below apply alongside the relevant setup guide.

Step 1: Replace the snippet

The Bloomreach Web SDK snippet is a full replacement for the Engagement JavaScript SDK snippet. The two snippets load different script files, use different credentials, and initialize different global objects.

Remove your existing Engagement JavaScript SDK snippet entirely and replace it with the Bloomreach Web SDK snippet from the appropriate setup guide linked in the table above.

The key differences to be aware of during the replacement:

After replacing the snippet, move to Step 2 if you have any existing code that references the exponea global object, such as weblayer scripts, tag manager tags, or custom tracking calls. If your codebase has no exponea references outside of the snippet itself, you can skip Step 2 and go straight to Step 3.

Step 2: Create the backwards compatibility alias (if needed)

If your website has any code outside the snippet that references exponea directly, for example, weblayer scripts configured in the Engagement dashboard, tags in Google Tag Manager, or custom exponea.track() calls, you need to create an alias so that the code continues to work after the snippet is replaced.

The alias maps exponea to brweb, so any call to exponea.track(), exponea.identify(), or other Engagement JavaScript SDK methods continue to function without changes.

Add the alias immediately after the closing }); of the new snippet configuration, before calling start():

  }); // new snippet configuration ends here
  window.exponea = brweb; // alias for backwards compatibility
  exponea.start();

📘

Note

The alias only needs to be added once, in the snippet itself. You do not need to update any of your existing exponea.track() or exponea.identify() calls. They will continue to work via the alias.

If you don't have any existing exponea references outside the snippet, call brweb.start() directly instead:

  }); // new snippet configuration ends here
  brweb.start();

Step 3: Verify the migration

Use the Bloomreach Tracking Console extension to confirm the migration is working correctly. Check that:

• Events are firing with the correct stream_id in the metadata
• The exponea alias resolves correctly if you added one (open your browser console and run exponea === brweb — it should return true)
• Visitor identification is working as expected
• No cookie collision errors appear in the console

What's next?

• Web tracking: Customer identification, event tracking methods, cookies, and storage
• Required events: Full reference for all events, properties, and API request examples
• Integrate on single-page applications: SPA-specific tracking considerations