Add Discovery to existing Engagement setup

This guide walks you through adding Discovery tracking to a website that already has Bloomreach Engagement running via the Engagement JavaScript SDK.

The most important thing to understand before you start: you do not need to replace exponea with brweb. After updating your snippet, keep using exponea.track() for all tracking calls, both your existing Engagement events and the new Discovery events you add. The updated snippet creates the brweb object internally and aliases it to exponea, so your existing code continues to work without any changes.

If you're starting from scratch with no existing Bloomreach tracking, see Set up Engagement and Discovery instead.

Prerequisites

Before you start, make sure the following have been completed:

Your Data hub workspace has been provisioned
A Bloomreach Discovery account has been provisioned
DNS records are configured for your custom tracking domain (CTD)

Update the tracking snippet

To add Discovery support, you need to add Discovery-specific keys to the track block in your existing snippet configuration. You don't replace the entire snippet, just expand it.

Locate the track object in your existing snippet configuration and add the following properties:

track: {
  default_properties: {
    page_title: "Yellow wide sweater with turtleneck | Pacific",
    customer_tier: "gold-member"  // your additional custom segments for Discovery
  },
  metadata: {
    domain_key: "Pacific",  // Bloomreach provided key for Discovery
    view_id: "en_US",       // Bloomreach provided key for Discovery
  }
}

page_title in default_properties: Discovery uses page_title to identify the current page context. Set it to a canonical, static value — especially if your website uses animated or marquee page titles that change dynamically. A stable, descriptive value ensures Discovery receives accurate page data on every event.

customer_tier in default_properties: This is an example of a custom segment property used for Discovery relevance-by-segment search personalization. Replace this with the segment attributes relevant to your implementation.

domain_key and view_id: These are your Discovery domain key and catalog's view_id. For more details, see Bloomreach Web SDK: Metadata.

Add Discovery tracking events

The following events are new (they don't exist in your current Engagement setup) and need to be implemented specifically for Discovery. Use exponea.track() for all of them, exactly as you do for your existing Engagement events.

For the full reference, including all properties, Discovery parameter mappings, and API request examples, see Required events. Your Bloomreach consultant or implementation partner will confirm which events and properties are required for your specific use cases.

view_homepage

Track this event when the homepage loads. Discovery maps this to a homepage page view (ptype=homepage).

exponea.track("view_homepage");

suggest_click

Track this event when a visitor clicks a suggested item in the search autocomplete. This includes keywords, products, categories, and content suggestions. Discovery maps this to a suggest event (etype=click, group=suggest).

function onSuggestClicked() {
  exponea.track("suggest_click", {
    q: "turtleneck",
    aq: "tur",
    catalogs: [
      {
        name: "products_en",
        view_ids: ["en_US"]
      }
    ]
  });
}

search_submit

Track this event when a visitor submits a search query. Discovery maps this to a search event (etype=submit, group=suggest).

function onSearchSubmitted() {
  exponea.track("search_submit", {
    q: "turtleneck",
    catalogs: [
      {
        name: "products_en",
        view_ids: ["en_US"]
      }
    ]
  });
}

view_search_results

Track this event on the search results page. Discovery maps this to a search page view (ptype=search).

exponea.track("view_search_results", {
  search_term: "turtleneck",
  catalogs: [
    {
      name: "products_en",
      view_ids: ["en_US"]
    }
  ]
});

view_other

Track this event on any page that doesn't match one of the other page view events. Discovery maps this to another page view (ptype=other).

exponea.track("view_other");

Additional Discovery events

The following events are also required for Discovery. Their implementation follows the same pattern as the events above — use exponea.track() with the properties described in the Required events reference.

Event	When to track
`view_content`	When a content item page loads, such as a blog post or article served by Discovery.
`view_thematic`	When a thematic page served by Discovery SEO loads.
`view_quickview`	When product details appear in a modal on the current page, such as a quickview popup.
`widget_view`	When Discovery Recommendations or Pathways widget results are displayed.
`widget_click`	When a visitor clicks an item in a Discovery widget.
`cart_update` (from a widget)	When a visitor adds an item to the cart directly from a Discovery widget.

Update the purchase event

Your existing purchase event needs to be expanded with additional properties for Discovery. The changes depend on how you're currently tracking purchases.

Add required Discovery properties

Add price_local_currency and local_currency to your existing purchase event, and confirm that purchase_status is set to "created" for placed orders. These properties are required for Discovery conversion tracking and currency handling.

For the full purchase property reference, see Purchase events.

If you track purchase_item separately

If your current setup tracks individual purchase_item events alongside purchase, add a product_list array to your purchase event instead. Once product_list is in place, stop tracking purchase_item separately. The system generates individual purchase item events from product_list automatically, and tracking both creates duplicates.

If you track purchase from the server side

Server-side purchase tracking requires the _br_uid_2 cookie value to be passed in the metadata block of your API request. This is the URL-decoded string value of the _br_uid_2 cookie from the visitor's browser.

For client-side tracking, the JavaScript SDK adds _br_uid_2 to metadata automatically. You don't need to include it manually.

Add the following to the metadata block in your server-side API command:

"metadata": {
  "_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw=="
}

For the full server-side tracking reference, including required HTTP headers, see Server-side tracking.

Verify your implementation

Use the Bloomreach Tracking Console extension to validate your updated tracking setup in the browser. It lets you inspect events as they fire, verify that Discovery metadata properties are passing correctly, and confirm that Discovery is receiving the expected data.

What's next?

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