HomeData hubOther resources
Guides

Set up event streams

Suggest Edits

This guide walks you through creating and configuring Event streams in Data hub to capture real-time customer data for Bloomreach Discovery and Engagement platforms.

Prerequisites

Before you begin, ensure you have:

  • Data hub workspace access with Event streams Admin role.

  • Bloomreach Engagement project and/or Discovery account provisioned.

  • Access to your app or website's code to implement tracking.

  • DNS management access for custom domain configuration (optional).

Create and configure event streams

Create an event stream

  1. Log in to Data hub and navigate to Events in the navigation menu on the left.

  2. Click + New event stream at the top right corner of the page.

  3. Name your event stream descriptively (include locale identifiers for multi-locale setups).

  4. Select the Stream type based on the data source (Web or Server-side tracking).

  5. Click Create to generate the event stream.

Configure custom tracking domain (optional but recommended)

Custom domains improve tracking reliability and data quality. A custom domain can be used as your Data hub tracking API endpoint.

You can configure custom domains in your Data hub workspace settings (Workspace settings > General > Domains). For detailed DNS configuration, see Custom Domain Management.

Copy integration credentials

After creating your event stream:

  1. Open the event stream details page (redirected automatically after you create a new stream).

  2. Copy the API credentials from the <script> tag:

    1. Target (API endpoint): Your default Data hub tracking base URL (or set up a custom tracking domain)
    2. Stream ID: Unique identifier for the event stream

  3. Store these credentials safely for your tracking implementation.

Connect destinations

Connect your event stream to process and store data:

  1. On the event stream setup page, switch to the Destinations tab.

  2. Click + Add destination and select one from the available options:

    • Engagement: Choose your target project from the list.

    • Discovery: Select your Discovery account.

  3. Repeat for additional destinations (maximum one destination per type).

  4. Click Save changes at the top right corner.

Adjust tracking permissions

Event stream permissions control what data can flow through the stream into Data Hub. Configure permission rules to prevent data pollution and separate untrusted client-side tracking from trusted backend tracking.

Permission types

Configure three types of rules for the event stream:

  • Customer ID permissions: Control which identifiers (cookie, registered, loyalty card) can link events to customer profiles

  • Customer property permissions: Determine which profile attributes (email, phone, membership status) can be updated through the stream

  • Event type permissions: Specify which events (page_visit, purchase, consent) the stream accepts

Read the Event stream permissions guide to learn more about the use cases and working of permissions.

📘

Note

The system provides default permissions based on the stream’s type (public or private). You may need to customize these for your specific tracking needs. Your Bloomreach technical consultant will guide you on which identifiers, properties, and event types to allow for your use case.

Configure permissions

  1. On the event stream setup page, switch to the Access Security tab.

  2. Scroll to the Permissions section.

  3. The permission templates are pre-configured for each stream type (public or private). Review the permissions and adjust based on your requirements:

    1. Toggle allow/deny for specific customer identifiers
    2. Enable or disable customer properties
    3. Select which event types to accept

  4. For private streams, generate a secret shared key to authenticate tracking API requests:

    1. Click Create new key in the Keys section
    2. Copy the secret immediately (displayed only once)
    3. Store it securely in your backend configuration

  5. Click Save changes to apply the permission rules.

Permission changes take effect within five seconds across the system. For detailed permission strategies and use cases, see Event stream permissions.

Deploy tracking implementation

Choose your tracking method and implement it on your website or application:

For Bloomreach Web SDK tracking:

  1. Add the Data hub Web snippet to your website's HTML <head> section.

  2. Configure the snippet with your stream ID and target endpoint.

  3. Set up the required event triggers for customer interactions.

For API tracking:

  1. Configure your backend to send HTTP POST requests to your Data hub tracking API endpoint at different interaction points.

  2. Include the stream_id as a query parameter in the request.

  3. Format event payloads according to the event schema requirements.

Validate tracking implementation

Verify your tracking works correctly across systems:

Browser validation:

  1. Install the Bloomreach tracking console extension (Chrome or Edge).

  2. Navigate to your website with tracking deployed.

  3. Open the extension to monitor tracked events in real time.

  4. Verify all required events fire with correct data.

Engagement validation:

  1. Open your connected Engagement project.

  2. Navigate to Data & Assets > Customers.

  3. Search for recent customer profiles.

  4. Check Data & Assets > Data manager to verify:

    • Customer properties are populating.

    • Events are recording correctly.

Discovery validation:

  1. Ensure you have configured test metadata in your tracking implementation:

    1. Add test_data=true to event metadata.

    2. Optionally include debug=true for real-time validation.

  2. Open your connected Discovery account.

  3. Navigate to Setup > Event diagnostics to review incoming events.

  4. Check Setup > Event alerts for any tracking errors or warnings.

For troubleshooting tracking issues, see Pixel Errors on Pixel Monitor.

Migrate from existing tracking

If you're currently using Engagement or Discovery tracking separately, follow this migration path to move your tracking logic to Data hub.

Migration prerequisites

Before migrating:

  1. Align with your Bloomreach CSM to confirm migration readiness.

  2. Activate the Data hub module in your account.

  3. Grant Event streams admin permissions to your team members.

Migration process

From Engagement tracking:

  1. Follow the SDK migration guide.

  2. Update your tracking implementation to use Data hub endpoints.

  3. Test thoroughly before switching production traffic.

From Discovery tracking:

  1. Reimplement your pixel integration using the Data hub SDK.

  2. Note that the new SDK won't read from Discovery's existing br_data variables.

  3. Plan for a complete tracking reimplementation.

Adding products to existing implementations

If you're adding Discovery to an existing Engagement implementation, follow the specific approach below to avoid data conflicts.

❗️

Compatibility warning

You cannot run both the Engagement JavaScript SDK and Bloomreach Web SDK (Data hub) simultaneously on the same website. These SDKs cause unexpected cookie collisions that lead to loss of visitor identification and tracking data. You must switch from one SDK to the other completely.

Add Discovery to existing Engagement tracking

For existing Engagement customers adding Discovery tracking through Data hub:

  1. Migrate the Engagement snippet: Replace your existing Engagement tracking with the Bloomreach Web SDK using the exponea alias for backward compatibility.

  2. Extend with Discovery metadata: Add Discovery-specific metadata and events to your unified tracking implementation.

  3. Avoid separate Discovery pixels: Do not add a separate Discovery tracking pixel alongside the unified Web SDK.

This unified approach ensures both platforms receive data without conflicts while maintaining your existing Engagement functionality through the alias configuration.

Development environment setup

Configure separate Event streams for development and production:

Engagement developers:

  • Create a development Event stream connected to your DEV Engagement project.

  • For production deployment:

    • Create a new Event stream with production credentials, or

    • Reconnect your existing Event stream to the PROD Engagement project.

Discovery developers:

  • Connect your Event stream to your Discovery account.

  • During development, include test metadata in your events:

    • Add test_data=true to event metadata.

    • Optionally include debug=true for real-time logging.

For test event configuration, see Track debug events in Integration mode.

Best practices

Multi-destination tracking

When connecting both Engagement and Discovery:

  • Use one Event stream connected to both destinations.

  • You can't use multiple Stream IDs on one website.

  • All events forward to both destinations after a successful connection.

Filter unwanted events (optional)

If you want to keep the data in Engagement clean when using it with Discovery:

  1. Navigate to Data & Assets > Data manager in Engagement.

  2. Add Discovery-specific event types (suggest_click, search_submit).

  3. Set these events to Forbidden status.

  4. Save your configuration to prevent these events from being stored.

Support resources

For additional support, contact your Bloomreach consultant or visit support.bloomreach.com.

Updated 1 day ago