The Bloomreach Engagement implementation playbook: Part 1

Introduction: Why implementation is the whole game

Bloomreach Engagement is often sold on its outcomes, predictive segmentation, AI-driven send times, unified customer profiles, and omnichannel orchestration. Those outcomes are real. But every experienced operator has seen the other side: six-figure contracts that produce duplicate profiles, misfiring scenarios, consent violations, and dashboards nobody trusts. Those failures trace back to how the platform was implemented, not to the platform itself.

The difference between a Bloomreach instance that earns its cost back in 90 days and one that becomes shelfware is almost never the platform. It’s the decisions made in the first month: how you model identity, how you name events, where you put logic, how you handle consent, and who owns the governance model after launch. When those decisions are sound, Bloomreach compounds in value over time; when they aren’t, every new campaign inherits the debt.

This series is the implementation playbook Scalero uses across enterprise Bloomreach projects. It’s written for two audiences working side by side: the CRM or marketing lead who needs to understand what “good” looks like, and the solutions architect or developer who has to build it. Each part works as a standalone reference and as one step in a complete rollout.

The six parts cover the full arc of a production implementation:

1. Foundation. SDK integration, identity architecture, and the pre-implementation decisions that shape everything downstream.

2. Data ingestion. Event taxonomy, attributes, historical imports, and the merging logic that keeps your single customer view honest.

3. Orchestration. Scenario design patterns, Jinja2 personalization, and the node-level choices that separate reliable automations from fragile ones.

4. Advanced channels. Catalogs, weblayers, mobile push, and the on-site experiences that extend Bloomreach beyond email.

5. Intelligent marketing. Loomi AI, predictive attributes, and the shift from static segments to probabilistic customer models.

6. Governance. Consent management, reporting architecture, access control, and the operational discipline that keeps the platform healthy over years, not quarters.

If you’re evaluating Bloomreach, this series should give you an honest view of the scope of work ahead. If you’re mid-implementation, treat it as a checklist. Every client we’ve audited has at least one part they skipped and later regretted. And if you’re inheriting an implementation from another team, start with Part 1 and work forward: it will usually surface the ten-minute fixes that unlock months of blocked work.

Let’s begin at the foundation.

Part 1: SDK integration and identity architecture

Every Bloomreach implementation begins with the same two deliverables: a working SDK deployment and a coherent identity schema. Both look mechanical on the surface, but each involves significant design judgment. The choices you make in the first week of implementation (which hard identifier to use, where the SDK loads, how consent is captured at first touch) will determine what your customer database looks like two years from now, when you have ten million profiles and a marketing team that has stopped trusting the numbers.

This part covers what to decide before you write any code, the technical mechanics of SDK deployment, and the identity architecture that keeps a Bloomreach instance clean at scale.

Before the SDK: the pre-implementation checklist

The single largest predictor of a successful Bloomreach rollout is whether the team invested in planning before touching the platform. The planning work falls into four buckets:

Stakeholder alignment. Bloomreach sits at the intersection of marketing, engineering, product, legal, and analytics. Before kickoff, agree on who owns each domain. Marketing typically owns scenarios and campaigns. Engineering owns the SDK and data layer. Analytics owns the tracking plan. Legal owns the consent framework. Without explicit ownership, everything becomes a marketing problem and nothing gets maintained.

Use case prioritization. List the first five customer experiences you want to build: welcome series, abandoned cart, post-purchase follow-up, win-back, browse abandonment. Every event, attribute, and catalog you build in implementation should trace back to one of these use cases. Without that discipline, teams instrument hundreds of events that never get used and miss the ones they actually need.

Tracking plan. This is the document that defines every event, every attribute, every customer property, and every catalog before any of it is implemented. Treat it as a contract between marketing and engineering. We’ll cover tracking plan design in depth in Part 2, but the point to internalize now is that the tracking plan precedes the code, not the other way around.

Environment strategy. You’ll need at least two Bloomreach projects: one for production and one for development or staging. Many mature clients run three (development, staging, production) to match their engineering release cycle. Decide this now, because retrofitting a staging environment after launch means re-importing historical data.

With those decisions made, the SDK work becomes straightforward.

Deploying the JavaScript SDK

The Bloomreach JavaScript SDK is the primary data collection mechanism for most web implementations. Scalero recommends initializing it through exponea.start() rather than the legacy exponea.initialize() call. The newer method supports asynchronous loading, exposes a cleaner configuration surface, and is the path the platform will continue to develop.

A production-ready initialization looks like this:

// Bloomreach Engagement SDK Initialization
exponea.start({
  token: "YOUR_PROJECT_TOKEN",
  target: "https://api.exponea.com",
  customer: {
    registered: "customer_id_123"
  },
  track: {
    default_properties: {
      app_version: "2.4.1",
      platform: "web"
    },
    google_analytics: false
  },
  experimental: {
    startup_flush_interval: 3000
  }
});

// Bloomreach Engagement SDK Initialization
exponea.start({
  token: "YOUR_PROJECT_TOKEN",
  target: "https://api.exponea.com",
  customer: {
    registered: "customer_id_123"
  },
  track: {
    default_properties: {
      app_version: "2.4.1",
      platform: "web"
    },
    google_analytics: false
  },
  experimental: {
    startup_flush_interval: 3000
  }
});

// Bloomreach Engagement SDK Initialization
exponea.start({
  token: "YOUR_PROJECT_TOKEN",
  target: "https://api.exponea.com",
  customer: {
    registered: "customer_id_123"
  },
  track: {
    default_properties: {
      app_version: "2.4.1",
      platform: "web"
    },
    google_analytics: false
  },
  experimental: {
    startup_flush_interval: 3000
  }
});

A few details matter more than they appear. The target should always match your region. Using the default US endpoint from an EU-hosted instance will fail silently until someone notices missing data two weeks in. The default_properties object attaches the listed attributes to every event, which is invaluable for debugging and cross-platform analysis. And the customer object should only include a registered identifier if one is known at page load; otherwise Bloomreach will create an anonymous cookie-only profile and stitch it to a hard ID when the user logs in.

Deployment options: direct, GTM, or server-side

How you load the SDK matters as much as what you pass to it. The three common options have distinct tradeoffs.

Direct integration. The SDK loads from your site’s codebase, giving the engineering team full control over initialization timing and configuration. This is the most reliable option for complex SPAs and the one we recommend for mature engineering teams. It also survives third-party script blockers best.

Google Tag Manager. GTM deployment lets marketing operate independently of engineering release cycles, which is attractive for teams with slow deploy cadences. The tradeoff is that GTM introduces a scripting layer between Bloomreach and your DOM, which can cause race conditions if the tag fires before the data layer is populated. If you go this route, use a custom HTML tag rather than the GTM template, and fire it on a dataLayer event rather than page view.

Server-side tracking. For high-sensitivity events (purchases, subscription changes, fraud signals), send events from your backend directly to the Bloomreach API using the customer’s registered ID. Server-side events are immune to ad blockers, consent popups, and race conditions, and they should always be the source of truth for revenue data. Most implementations use a hybrid: client-side for engagement events, server-side for transactional events.

Mobile SDKs follow the same pattern, with separate libraries for iOS (Swift) and Android (Kotlin/Java). Mobile implementations are out of scope for this part but follow the same identity rules covered next.

The identity architecture

Bloomreach profiles are keyed by one or more external IDs. These are the values that tie a profile to your backend and let the platform stitch anonymous sessions to known customers. The choice of external IDs is the single highest-leverage decision in the entire implementation.

At minimum, you need two:

1. A hard identifier (registered by default). This is the permanent, case-sensitive identifier that uniquely and stably identifies a human. It should be generated by your backend and remain unchanged for the customer’s lifetime, regardless of how many times they change email addresses, phone numbers, or account preferences.

2. A soft identifier (cookie by default). Automatically generated by the SDK on first visit, this tracks anonymous sessions and gets stitched to the hard ID on login or signup.

Avoid the temptation to use email as the hard ID. When a customer changes their email address (and across a five-year relationship (many will)) you now have two profiles that both claim to be the same person, with no backend way to merge them. Worse, email is case-insensitive in practice but case-sensitive in Bloomreach, so User@Example.com and user@example.com will create duplicate profiles from the same login attempt.

💡Scalero’s standard pattern: use an immutable backend UUID or customer number as registered, and store email as a customer attribute rather than an ID. This gives you one permanent anchor for historical data and the flexibility to change email freely without fragmenting the single customer view.

For organizations with multiple systems, you can configure additional external IDs (for example, loyalty_id, crm_id, erp_id) to support identity resolution across business domains. Each additional ID is a hard identifier with its own merge behavior, so add them deliberately.

Inside Project Settings, normalize every identifier with an Attribute Transformation. At minimum, apply Lowercase and Trim to all email-like fields. This is the single highest-ROI five-minute change you can make during implementation.

Consent at initialization

Consent is covered in depth in Part 6, but two critical decisions belong in this phase:

First, decide your execution strategy:

• Strict (EU/GDPR): The SDK is blocked until the user clicks "Accept."

• Permissive (US/CCPA): The SDK tracks anonymously immediately but honors "Opt-out" settings.

Second, structure your identify call to match that strategy. Getting consent into the profile during initialization—rather than as an afterthought—saves an enormous amount of cleanup work.

Pattern A: Strict Mode (Post-Consent)
Use this if you are wrapping the call in a "Cookie Accept" event.

// Triggered only after the user clicks 'Accept'
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: true,
    cookies: "accepted"
  }
});

// Triggered only after the user clicks 'Accept'
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: true,
    cookies: "accepted"
  }
});

// Triggered only after the user clicks 'Accept'
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: true,
    cookies: "accepted"
  }
});

Pattern B: Permissive Mode (On Load)
Use this if you are firing the SDK immediately but want to remain compliant.

// Fires immediately; defaults to 'false' until the user opts in
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: false, 
    cookies: "pending"
  }
});

// Fires immediately; defaults to 'false' until the user opts in
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: false, 
    cookies: "pending"
  }
});

// Fires immediately; defaults to 'false' until the user opts in
exponea.identify({
  registered: "customer_id_123"
}, {
  email: "user@example.com"
}, {
  consent: {
    marketing: false, 
    cookies: "pending"
  }
});

Getting consent into the profile during initialization, rather than as an afterthought later, saves an enormous amount of cleanup work.

QA: the debugger is your best friend

Before you declare the SDK deployment done, spend a full day in the Bloomreach debugger. Open it on every page template, confirm events fire with the expected attributes, confirm identity stitches cleanly across login flows, and confirm default properties propagate. The debugger will catch 90% of the problems that would otherwise take weeks to surface in production data.

The three failure modes to test explicitly:

• Anonymous → authenticated stitch. Browse anonymously, add to cart, log in, verify that the cart event now belongs to the authenticated profile.

• Cross-device stitch. Log in on desktop, then on mobile, verify the profile merges correctly.

• Logout and re-login as a different user. A common bug is that the customer object persists across sessions, causing the second user’s events to land on the first user’s profile. Test explicitly.

With the foundation set, the next question is what data flows through it. Part 2 covers the event architecture.