Forward events to Bloomreach

Send Snowplow events to Bloomreach Engagement for real-time customer analytics, segmentation, and personalization using the Batch Commands API.

Prerequisites

Before setting up the forwarder in Console, you'll need to configure an API key with 'Get' and 'Set' permission on all of the properties events that you intend to send to bloomreach. We recommend also permitting 'Get' and 'Set' permission on 'New Properties' and 'New Events', do avoid problems when new tracking is added.

You can configure this in the Access Management section of Project settings.

You'll also need the following from your Bloomreach Engagement account:

• API Endpoint Host: the base URL for your Bloomreach API instance (e.g., api.exponea.com)
• Project Token: a unique identifier for your Bloomreach project
• API Key ID: the identifier for your API key
• API Secret: the secret associated with your API key. Save the secret in a secure location, as you can only view it once after creation.

You can find all of these values in Bloomreach under Project settings > Access management > API.

Test in a non-production project first

To avoid introducing test data in your production Bloomreach project, we recommend using a test or development project to test your transformations first. Then, create a new connection in Console with your production credentials, and a new forwarder that imports the configuration from your development forwarder.

Getting started

Configure the destination

To create the connection and forwarder, follow the steps in Creating forwarders.

When configuring the connection, select Bloomreach for the connection type and enter your API endpoint host, project token, API key ID, and API secret.

Validate the integration

You can confirm events are reaching Bloomreach by checking the customer profiles in your Bloomreach Engagement project:

1. In Bloomreach, navigate to Data & Assets > Customers
2. Search for a customer whose events you have forwarded
3. Open the customer profile and check the Events tab to verify that your Snowplow events appear

Identity management

Bloomreach uses a combination of hard and soft customer IDs to identify and merge customer profiles. The Snowplow integration defaults to using user_id as the hard ID (registered) and domain_userid as the soft ID (cookie).

When a user is anonymous, Bloomreach tracks their activity using the soft ID. When the user logs in and your event contains a user_id value, Bloomreach merges the anonymous profile with the identified profile, linking prior anonymous activity to the known customer.

The ID type names (registered, cookie) must match the customer ID types configured in your Bloomreach project. You can customize these mappings in the forwarder configuration if your project uses different ID type names.

Sending custom properties

You can send custom event properties beyond the standard fields defined in the schema reference below. Custom properties are nested under the properties object. When configuring your forwarder, add field mappings formatted as properties.your_custom_field (e.g., properties.plan_type, properties.feature_flag).

For property names containing spaces, use bracket notation (e.g., properties["referred by"]).

See Bloomreach's Batch Commands API documentation for details on supported data types and property requirements. See Creating forwarders for details on configuring field mappings.

Schema reference

This section contains information on the fields you can send to Bloomreach, including field names, data types, required fields, and default Snowplow mapping expressions.

Field	Details
customer_ids object	Required. Object identifying the customer. Must contain at least one ID. Keys are ID type names configured in the Bloomreach project. Properties: registered (string, optional): Hard ID — the identified user ID. Used for cross-device identity resolution. Default mapping: event.user_id cookie (string, optional): Soft ID — anonymous visitor identifier, typically a browser cookie. Default mapping: event.domain_userid
event_type string	Required. The name of the event type in Bloomreach. Default mapping: event.event_name
timestamp integer	Optional. When the event occurred, as UNIX epoch seconds. Defaults to current time if omitted. Default mapping: Math.floor(spTstampToJSDate(event.derived_tstamp).getTime() / 1000)
properties object	Optional. Arbitrary key-value pairs for the event. Values can be strings, numbers, booleans, or nested objects. Properties: url (string, optional): The full URL of the page where the event occurred. Default mapping: event.page_url title (string, optional): The page title. Default mapping: event.page_title referrer (string, optional): The referring URL. Default mapping: event.page_referrer ip (string, optional): The user's IP address. Default mapping: event.user_ipaddress city (string, optional): The city of the user. Default mapping: event.geo_city region (string, optional): The region (state or province) of the user. Default mapping: event.geo_region_name || event.geo_region country (string, optional): The country code of the user. Default mapping: event.geo_country latitude (number, optional): Latitude of the user's location. Default mapping: event.geo_latitude longitude (number, optional): Longitude of the user's location. Default mapping: event.geo_longitude browser (string, optional): Name of the browser. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.agentName browser_version (string, optional): Version of the browser. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.agentVersion os (string, optional): Operating system name. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.operatingSystemName || event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.osType os_version (string, optional): Operating system version. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.operatingSystemVersion || event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.osVersion device (string, optional): Device name or model. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.deviceName || event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.deviceModel device_type (string, optional): The type/class of device (e.g. Desktop, Mobile, Tablet). Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.deviceClass device_manufacturer (string, optional): Manufacturer of the device. Default mapping: event.contexts_nl_basjes_yauaa_context_1?.[0]?.deviceBrand || event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.deviceManufacturer screen_height (integer, optional): Device screen height in pixels. Default mapping: event.dvce_screenheight screen_width (integer, optional): Device screen width in pixels. Default mapping: event.dvce_screenwidth language (string, optional): The user's language/locale. Default mapping: event.contexts_com_snowplowanalytics_snowplow_browser_context_1?.[0]?.browserLanguage || event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.language timezone (string, optional): The user's timezone. Default mapping: event.os_timezone platform (string, optional): The platform the event was tracked on (web, mob, etc.). Default mapping: event.platform tracker (string, optional): Tracker library that sent the event. Default mapping: 'Snowplow: ' + event.v_tracker utm_source (string, optional): UTM source parameter. Default mapping: event.mkt_source utm_medium (string, optional): UTM medium parameter. Default mapping: event.mkt_medium utm_campaign (string, optional): UTM campaign parameter. Default mapping: event.mkt_campaign utm_content (string, optional): UTM content parameter. Default mapping: event.mkt_content utm_term (string, optional): UTM term parameter. Default mapping: event.mkt_term carrier (string, optional): Mobile carrier. Default mapping: event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.carrier network_type (string, optional): Network connection type (wifi, mobile, etc.). Default mapping: event.contexts_com_snowplowanalytics_snowplow_mobile_context_1?.[0]?.networkType app_version (string, optional): Application version. Default mapping: event.contexts_com_snowplowanalytics_mobile_application_1?.[0]?.version || event.contexts_com_snowplowanalytics_snowplow_application_1?.[0]?.version