Bloomreach

Commerce-focused customer data and experience platform combining real-time customer data, AI-driven personalisation, and marketing automation.

Signal delivers events into a Bloomreach Data Hub event stream. Data Hub is Bloomreach’s unified ingestion layer: one stream validates incoming events against its own permission rules and then fans them out to whichever Bloomreach products are connected to it (Marketing/Engagement, Search).

Why route Bloomreach through Datafly Signal

• Profiles are updated from the server, not the browser. Events reach Bloomreach even when a tracker blocker or a failed page unload would have dropped a client-side call, so the profile reflects what actually happened.
• Client IP and user agent are preserved. Server-to-server delivery normally loses both, which weakens matching. Signal forwards the genuine visitor values as request headers so Bloomreach attributes the event to the right session.
• Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the Bloomreach rate limit, and retries on 429 or transient failure rather than dropping the event.
• Presets for Retail and General (all verticals). The mapping starts from a working configuration for your vertical instead of a blank field map.
• One consent decision governs every destination. Bloomreach is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

Complete these steps in Bloomreach before configuring Signal.

Configuration

Signal Setup

Quick Setup

1. Navigate to Integrations in the sidebar.
2. Open the Integration Library tab.
3. Find Bloomreach under the CDP category.
4. Click Install, and fill in the required fields with the credentials gathered above.
5. Click Install Integration to create the integration with a ready-to-use default configuration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/bloomreach_cdp/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bloomreach",
    "variant": "default",
    "config": {
      "target_base_url": "api-engagement.bloomreach.com",
      "stream_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "api_key_id": "xxxxxxxxxxxxxxxxxxxx",
      "api_secret": "xxxxxxxxxxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

Bloomreach Data Hub defines its own required-event taxonomy, which is page-type specific rather than action-generic. The blueprint maps Signal’s canonical events onto it:

Signal’s items array is reshaped into Bloomreach’s product_list shape (product_id, variant_id, title, price, quantity).

Page views: pick the preset that matches your site

Bloomreach’s view_* family is its page-view taxonomy, and each member maps to a Search ptype. view_other means “a page that isn’t one of the other types”, so it is a real page type rather than a generic fallback. That makes it important to send exactly one page-view event per page load, correctly typed.

Signal ships two presets because the right way to do that differs by vertical.

Retail uses the explicit ecommerce events, since view_item and view_item_list already carry the page type:

page is unmapped here. It fires automatically on every page load, so mapping it as well would count every product and listing page twice, with two conflicting page types.

General (all verticals) is for publishing, media, SaaS, finance, travel, and anything else without ecommerce events. Here page is the single page-view event, typed from the optional page_type property:

datafly.page({ page_type: 'content' })   // → Bloomreach view_content, Search ptype=content

The mapping has no wildcard, so an absent or unknown page_type falls back to view_other rather than mislabelling the page. A site sending no page_type at all still gets valid page views, just all classified as “other”.

Consent

Bloomreach records consent as a first-class event with action, category, valid_until, and a timestamp that becomes the consent’s valid_from. An invalid consent event revokes the customer’s consent, by Bloomreach’s explicit design, on the basis that if it cannot tell whether to accept or reject it fails to the safe side.

The blueprint ships a consent mapping, disabled by default, built around that:

Enable it only when you have decided Signal owns a specific Bloomreach consent category, captured from a Signal-instrumented touchpoint such as a newsletter signup or preference centre. See the consent event spec for how to emit it.

Signal is one consent source among several (source: private_api in Bloomreach’s record). It cannot see the email channel, so unsubscribes that happen in an email footer will not reach Signal. Leave Bloomreach’s own list_unsubscribe, consent page, and double opt-in mechanisms in place to cover those.

Identity

Signal forwards the following identifiers to Bloomreach customer_ids:

Call datafly.identify() on login or form submission to maximise profile unification:

datafly.identify("user-123", { email: "jane@example.com" });

Every identifier must also be allowed on the stream’s Customer IDs permission list. An identifier that Signal sends but the stream denies is dropped by Bloomreach, and the delivery still returns success.

Anonymous visitors

Anonymous identity is configured in Bloomreach, in two separate places. Both have to be right, and neither reports a problem to Signal when it isn’t.

1. The project’s identifier definitions

Bloomreach distinguishes two identifier types:

Bloomreach creates a profile for every first-time visitor keyed on the soft ID, then links that history to the hard ID when the visitor logs in or purchases. That is the mechanism which makes pre-login activity count, so the cookie mapping is what makes anonymous attribution work at all — it is marked required in the blueprint for that reason.

Two limits worth knowing before you design around soft IDs:

• 64 soft IDs per profile, per type. Beyond that Bloomreach discards the least-recently-used one together with its data. A visitor churning cookies (private browsing, many devices) can silently lose history.
• Hard IDs are case-sensitive. Jane@example.com and jane@example.com become two profiles. Normalise to lowercase before sending — Signal’s normalised_sha256 convention already trims and lowercases, and the same discipline applies here even though Bloomreach wants the raw value rather than a hash.

2. The event stream’s Customer IDs permissions

Separately, each event stream has an allow-list. Under Data hub > Events > your stream > Access security > Permissions > Customer IDs, every identifier is set to Allow, Signed only, or Deny, with a default for identifiers not on the list.

A newly created stream commonly lists only registered. If cookie is absent and the undefined-ID default is Deny, then every pre-login event arrives with no usable identifier — Bloomreach discards it, and the API still returns HTTP 200. Nothing in Signal’s Live Events view will look wrong.

So: add cookie to the Customer IDs list and set it to Allow. Leave undefined IDs denied — that is good hygiene, it just means the list has to be complete.

Why this is server-side in the first place

Bloomreach documents three ways to keep anonymous identity durable, and names “server-side handling of identification of anonymous users by your infrastructure” as its recommended option for organisations with strong security, privacy, and compliance requirements. That is precisely what Signal does — it is the productised version of the approach Bloomreach otherwise expects you to build and maintain yourself.

The problem all three options address is browser cookie lifetime. Safari’s ITP caps JavaScript-set cookies at 7 days, or 24 hours where the domain is classed as a cross-site tracker, so a returning visitor reappears as a brand-new anonymous profile and their pre-login history fragments. Bloomreach’s own guidance is explicit that a CNAME-based tracking domain does not escape this — only NS-zone DNS records do. This is the same reason Signal requires its collect domain to be an A record, never a CNAME: the identity cookie is set server-side, first-party, on a host the browser has no reason to treat as third-party.

Bloomreach Search

If Search is connected to the stream, two additional pieces of data matter:

• _br_uid_2 — the Bloomreach Search cookie. Bloomreach requires it for server-side purchase attribution. The Bloomreach Web SDK sets it browser-side; a server-side pipeline can only forward it, so pass it through as a br_uid_2 event property and the blueprint maps it to metadata._br_uid_2.
• domain_key and view_id — Search routing values specific to your workspace. Add them as static mappings to metadata.domain_key and metadata.view_id in the integration’s field mappings.

Signal also forwards the visitor’s IP and User-Agent as X-Forwarded-For and User-Agent headers. Bloomreach reads geolocation from X-Forwarded-For and cannot infer it from the connecting server’s IP, so these are required for accurate location reporting and device audience targeting.

Consent

Bloomreach events should typically be sent under the marketing consent category. Bloomreach also exposes its own consent management settings within campaigns — Signal forwards the visitor’s CMP consent state on every event so Bloomreach can honour campaign-level suppression rules.

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the Data Hub tracking API. No client-side scripts are loaded for this integration.

The tracking API is a batch command endpoint, so Signal batches events into a single request:

POST https://TARGET/track/u/v1/batch?stream_id=STREAM_ID
Authorization: Basic base64(KEY_ID:SECRET)

{"commands":[{"name":"customers/events","data":{ ... }}]}

Verify it’s working

1. After installing the integration, trigger a test event from your website or via the Signal event API.
2. In Signal, check Live Events to confirm delivery with a 200 response status.
3. In Bloomreach, open the event stream and check its delivery/diagnostics view to confirm the stream accepted the event rather than rejecting it on a permission rule.
4. In the connected Bloomreach project, navigate to Data & Assets > Events and search for recent events.
5. Search for the test customer in Customers to verify the profile was created or updated.

Troubleshooting

See also

• Lytics — behavioural-scoring CDP
• Salesforce CDP — enterprise CDP
• Klaviyo — email and SMS marketing