SDK tracking required events details
Welcome note
Data hub is our new upgraded platform, which we rolled out in August 2025. It offers a single unified integration for passing your data through to your Bloomreach products.
You have access to Data hub if you've implemented with Bloomreach after August 2025.
Customers who have implemented before August 2025 should follow the existing documentation for Engagement, Discovery, and Clarity.
Tracking required events
Track your basic web user interactions. The full list of events names and properties depen
d on selected use cases. Refer to the Automatic tracking document and data requirements.
- Page view pixels (Track these events when a page loads, refreshes, or when content changes)
- view_homepage
- view_item (PDP)
- view_category (PLP)
- view_search_results
- purchase
- view_content
- view_thematic
- view_other
- Event pixels (Track these events on user interactions)
- cart_update (ATC)
- search_submit
- suggest_click
- view_quickview
- widgets
- view
- click
- ATC
Track view_homepage
- Track this event when homepage loads.
- This event will show in Discovery as "Homepage page view" (ptype=homepage)
brweb.track("view_homepage");
| Event property | Mapped to Discovery param |
|---|---|
| ptype=homepage |
Track suggest_click
- Track this event when user clicks on any suggested item (suggested item can be keyword, product, category, content)
- This event is an intent to search.
- This event will show in Discovery as "Suggest event" (etype=suggest)
function onSuggestClicked() {
brweb.track("suggest_click", {
q: "turtleneck",
aq: "tur",
catalogs: [
{
name : "products_en",
view_ids: ["en_US"]
}
]
});
}
| Event property | Mapped to Discovery param |
|---|---|
| q | q |
| aq | aq |
| catalogs | catalogs |
| etype=click | |
| group=suggest |
Example: suggest_click API request (on next page with view_search_results):
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "suggest_click",
"properties": {
// custom event properties
"q": "turtleneck",
"aq": "tur",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/",
"referrer": "https://www.google.com/", // optionally on blocklist for Engagement
// Engagement specific
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
"debug": true,
"test_data": true,
},
"timestamp": 1749545984.2786303
}
},
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "view_search_results",
"properties": {
// custom event properties
"search_term": "turtleneck",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/en/catalogsearch/result?q=turtleneck",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==", // cookie2 param
"domain_key": "Pacific",
"view_id": "en_US",
"debug": true,
"test_data": true,
},
"timestamp": 1749545984.2786303,
"deferred_event": {
"type": "suggest_click",
"properties": {
"q": "turtleneck",
"aq": "tur",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
}
},
}
}
]
}
Track search_submit
- Track this event when user submits a search query.
- This event is an intent to search.
- This event will show in Discovery as "Search event" (etype=suggest)
function onSearchSubmitted() {
brweb.track("search_submit", {
q: "turtleneck",
catalogs: [
{
name : "products_en",
view_ids: ["en_US"]
}
]
});
}
| Event property | Mapped to Discovery param |
|---|---|
| q | q |
| catalogs | catalogs |
| etype=submit | |
| group=suggest |
Example: search_submit API request (on next page with view_search_results):
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "search_submit",
"properties": {
// custom event properties
"q": "turtleneck",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/",
"referrer": "https://www.google.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
},
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "view_search_results",
"properties": {
// custom event properties
"search_term": "turtleneck",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/en/catalogsearch/result?q=turtleneck",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"deferred_event": {
"type": "search_submit",
"properties": {
"q": "turtleneck",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
]
}
},
"timestamp": 1749545984.2786303
}
}
]
}
Track view_search_results
- Track this event on search results page
- This event will show in Discovery as "Search page view" (ptype=search)
brweb.track("view_search_results", {
search_term: "turtleneck",
catalogs: [
{
name : "products_en",
view_ids: ["en_US"]
}
]
});
| Event property | Mapped to Discovery param |
|---|---|
| search_term | search_term |
| catalogs | catalogs |
| ptype=search |
Example: view_search_results API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "view_search_results",
"properties": {
// custom event properties
"search_term": "turtleneck",
"catalogs": [
{
"name" : "products_en",
"view_ids": ["en_US"]
}
],
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/en/catalogsearch/result?q=turtleneck",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Track view_category
- Track this event on product listing pages, or category listing pages.
- This event will show in Discovery as "Category page view" (ptype=category).
brweb.track("view_category", {
category_id: "650",
title: "Turtlenecks",
category_level_1: "Clothes",
category_level_2: "Sweaters",
category_level_3: "Sweaters & Cardigans"
});
| Event property | Mapped to Discovery param | Note | ||
|---|---|---|---|---|
categories_path | cat | if categories_path contains ` | ` (vertical bar) | then it's mapped to cat |
title | cat | if categories_path doesn't contain ` | ` (vertical bar) | then title is mapped to cat |
category_id | cat_id | |||
ptype=category |
Example: view_category API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "view_category",
"properties": {
// custom event properties
"category_id": "650",
"title": "Turtlenecks",
"category_level_1": "Clothes",
"category_level_2": "Sweaters",
"category_level_3": "Sweaters & Cardigans",
// added by SDK automatically
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
"location": "https://www.pacific.com/en/clothing/sweaters-cardigans/turtleneck.html",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Track view_item
- Track this when product detail page is loaded.
- This event is an impression of a product.
- It will show in Discovery as "Product page view" (ptype=product).
brweb.track("view_item", {
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
price: 49.99
});
| Event property | Mapped to Discovery param |
|---|---|
| title | prod_name |
| product_id | prod_id |
| variant_id | sku |
| ptype=product |
Example: view_item API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"age": 0.10100007057189941,
"event_type": "view_item",
"properties": {
// custom event properties
"title": "Yellow wide sweater with turtleneck",
"product_id": "119479",
"variant_id": "MJ12199-0400",
"price": 49.99,
// added by SDK automatically
"page_title": "Yellow wide sweater with turtleneck | Pacific",
"lang": "en-US",
"location": "https://www.pacific.com/en/yellow-wide-sweater-with-turtleneck.html",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Track cart_update
- Track this event with
action=addwhen user adds an item to the cart.- It will show in Discovery as "Add to cart" (etype=cart).
- Track this event with
action=removewhen user removes an item from the cart.- Remove event will not show in Discovery
product_listis a snapshot of contents of the cart after the change (end state).- Only 1 ID/item is allowed to be added. When adding more items at once, you should track an event for each.
- This event is user interaction with a shopping cart.
brweb.track("cart_update", {
action: "add", // add to cart
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
product_list: [
{
product_id: "119479", quantity: 2
}
],
total_price: 99.98 // in USD reference currency for Engagement
});
| Event property | Mapped to Discovery param |
|---|---|
| title | prod_name |
| product_id | prod_id |
| variant_id | sku |
| prod_collection_id | prod_collection_id |
| etype=click-add | |
| group=cart |
brweb.track("cart_update", {
action: "remove", // remove from cart
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
product_list: [
{
product_id: "119479", quantity: 1
}
],
total_price: 49.98
});
Example: cart_update API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9",
},
"event_type": "cart_update",
"properties": {
"action": "add",
"title": "Yellow wide sweater with turtleneck",
"product_id": "119479",
"variant_id": "MJ12199-0400",
"product_list": [
{
"product_id": "119479",
"quantity": 2
}
],
"total_price": 99.98,
"location": "https://www.pacific.com/en/clothing/sweaters-cardigans/turtleneck.html",
"referrer": "https://www.pacific.com/",
"os": "Windows",
"browser": "Chrome",
"device": "Other",
"page_title": "Pacific | Clothing & accessories",
"lang": "en-US",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Track purchase
- Track event with
purchase_status=createdwhen order is placed (thank you page)- It will show in Discovery as "Conversion page view" (ptype=conversion).
- This event marks a successful conversion.
- Optionally you can track also other statuses, for example when an order is paid, or items returned.
- Track purchase from server-side if you wish to add sensitive information (e.g. costs, margins)
- Purchase normalization - The system automatically generates individual
purchase_itemevents from the items in theproduct_list(objects in the list must haveproduct_idandquantityset). - Limitations:
product_listcan be max 1000 items (items of a list, NOT a sum of quantity). Event size limit is 800 kB.- If you need to track an event with more than 1000 items, you can still do that if it's less than 800kB, but Bloomreach system will not generate individual
purchase_itemevents. In case you have more than 1000 line items, track these additionally.
- If you need to track an event with more than 1000 items, you can still do that if it's less than 800kB, but Bloomreach system will not generate individual
brweb.track("purchase", {
purchase_id: "ID123",
purchase_status: "created",
total_price: 107.72, // in USD reference currency for Engagement
local_currency: "EUR", // for Engagement as display currency and for Discovery currency conversion
price_local_currency: 99.98, // // in displayed currency EUR and for Discovery currency conversion
product_list: [
{
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
price: 53.86, // in USD reference currency for Engagement
price_local_currency: 49.99, // in displayed currency EUR and for Discovery currency conversion
quantity: 2
}
]
});
| Event property | Mapped to Discovery param |
|---|---|
| purchase_id | order_id |
| price_local_currency | basket_value |
| local_currency | currency |
| product_list[n].product_id | basket.items.prod_id |
| product_list[n].variant_id | basket.items.sku |
| product_list[n].title | basket.items.name |
| product_list[n].quantity | basket.items.quantity |
| product_list[n].price_local_currency | basket.items.price |
| ptype=conversion |
brweb.track("purchase", {
purchase_id: "ID123",
purchase_status: "return",
total_price: -53.86,
product_list: [
{
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
price: -53.86, // in USD reference currency for Engagement
quantity: -1
}
]
});
Example: purchase API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"email_id": "[email protected]",
},
"type": "purchase",
"properties": {
"purchase_id": "ID123",
"purchase_status": "created",
"total_price": 107.72,
"local_currency": "EUR",
"price_local_currency": 99.98,
"product_list": [
{
"title": "Yellow wide sweater with turtleneck",
"product_id": "119479",
"variant_id": "MJ12199-0400",
"price": 53.86,
"price_local_currency": 49.99,
"quantity": 2
}
],
"location": "https://www.pacific.com/en/order_complete",
"referrer": "https://www.pacific.com/en/checkout",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Track view_content
- It will show in Discovery as "Conversion page view" (ptype=content).
brweb.track("view_content", {
item_id: "article-123",
title: "How to choose you turtleneck sweater",
catalogs: [
{
name : "content_en",
view_ids: ["en_US"]
}
]
});
| Event property | Mapped to Discovery param |
|---|---|
item_id | item_id |
title | item_name |
catalogs | catalogs |
ptype=content |
Track view_thematic
- Track this event when Thematic page served by Discovery SEO is loaded.
- It will show in Discovery as "Conversion page view" (ptype=thematic).
brweb.track("view_thematic");
| Event property | Mapped to Discovery param |
|---|---|
ptype=thematic |
Track view_other
- Track this event on any other page that can't be recognised as any of the above page load events.
- It will show in Discovery as "Other page view" (ptype=other).
brweb.track("view_other");
| Event property | Mapped to Discovery param |
|---|---|
ptype=other |
Track view_quickview
- Track this event when showing product details in a modal on the currently visible page
- Usually this is displayed as a popup on product listing page (so called Quickview)
- It will show in Discovery as "Other page view" (etype=quickview).
brweb.track("view_quickview", {
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400"
});
Track widget_view
- Track this event when showing recommended products by Discovery Recommendations and Pathways feature.
- This event is an impression of your widget.
- It will show in Discovery as "Widget View event" (etype=widget-view).
brweb.track("widget_view", {
widget_response_id: "abcd123",
widget_query: "turtleneck",
widget_id: "asd238",
widget_type: "mlt"
});
Track widget_click
- Track this event when showing recommended products by Discovery Recommendations and Pathways feature.
- It will show in Discovery as "Widget View event" (etype=widget-view).
- This event is an interaction with an item from the widget.
brweb.track("widget_click", {
widget_response_id: "abcd123",
widget_query: "turtleneck",
widget_id: "asd238",
widget_type: "mlt",
item_id: "119479"
});
Track cart_update from a widget
-
Track this event when showing recommended products by Discovery Recommendations and Pathways feature.
-
It will show in Discovery as "Widget View event" (etype=widget-view).
-
This event is an interaction with an item from the widget.
-
Track this event with
action=addwhen user adds an item to the cart.- It will show in Discovery as "Widget Add to cart" (etype=cart).
-
This event is user interaction with a shopping cart.
brweb.track("cart_update", {
widget_response_id: "abcd123",
widget_query: "turtleneck",
widget_id: "asd238",
widget_type: "mlt",
action: "add", // add to cart
title: "Yellow wide sweater with turtleneck",
product_id: "119479",
variant_id: "MJ12199-0400",
product_list: [
{
product_id: "119479", quantity: 2
}
],
total_price: 99.98 // in USD reference currency for Engagement
});
Automatically added data
Customer IDs
- $customer_ids.cookie
- $customer_ids.registered (if identify without ID name is used)
Metadata
- $metadata._br_uid_2
- $metadata.domain_key
- $metadata.view_id
- $metadata.debug
- $metadata.test_data
Event properties
- page_title
- location
- rel_canonical
- referrer
- browser
- device
- os
- utm_source
- utm_medium
- utm_medium
- utm_campaign
- utm_term
- utm_content
- gclid
- campaign_id
Deferred events for Discovery
Deferred events are special type of events for Discovery, which are attached to the next page view event.
JS SDK will add deferred events (as deferred_event) for these event types:
- view_homepage
- view_category
- view_item
- view_content
- view_search_results
- view_thematic
- view_other
- purchase (not used)
Events that are deferred automatically by JS SDK:
Event properties from a deferred event are appended to the pageview event with a prefix df_. Example: Deferred event property search_submit.q is appended as view_search_results.df_q for Discovery.
| Event property | Mapped to Discovery param |
|---|---|
df_etype=click | |
df_group=suggest | |
df_type=event | |
q | df_q |
aq | df_aq |
catalogs | df_catalogs |
Server side tracking
- You can track all events directly to the API. This can be used for server-side tracking for both Engagement and Discovery.
The client IP address and User-Agent are crucial HTTP-level details often needed for tracking, especially for functionalities like geolocation and audience targeting based on device within Bloomreach.
When implementing server-side tracking, your server receives the original HTTP request from the user's browser. This request contains the client's IP address and User-Agent string in the standard HTTP headers. To pass this information to Bloomreach Tracking API (which serves as the endpoint for server-side integrations), you would include these details in the HTTP request your server makes to the API:
- Client IP Address: The client's IP address should typically be included in the
X-Forwarded-ForHTTP header of the request your server sends to the Bloomreach API. This is a standard header used to pass the original client's IP address when the request passes through proxy servers. The Bloomreach system is designed to parse a client's IP address from this header, therefore, the API needs to receive it from your server initially. - User-Agent: The user's browser's User-Agent string should be included in the standard
User-AgentHTTP header of the request your server sends to the Bloomreach API. This header provides information about the user's browser, operating system, and device type.
POST to your API endpoint https://tracking-api.bloomreach.co/track/u/v1/batch?stream_id=STREAM_ID
- Add
stream_idURL param with one from you Event stream credentials page. - Add
X-Forwarded-ForHTTP header with client's IP address for geolocation use cases. - Add
User-AgentHTTP header with client's user agent for device audience targeting use cases.
Example: purchase API request:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"email_id": "[email protected]",
},
"type": "purchase",
"properties": {
"purchase_id": "ID123",
"purchase_status": "created",
"total_price": 107.72,
"local_currency": "EUR",
"price_local_currency": 99.98,
"product_list": [
{
"title": "Yellow wide sweater with turtleneck",
"product_id": "119479",
"variant_id": "MJ12199-0400",
"price": 53.86,
"price_local_currency": 49.99,
"quantity": 2
}
],
"location": "https://www.pacific.com/en/order_complete",
"referrer": "https://www.pacific.com/en/checkout",
},
"metadata": {
"_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6:cdp_segments=NjY1MGUwZjEzMzdmODlhMmViZTY2Y2FiOjY2NTcyMmI2NGQwYWIyMmQ2NTYzODgwMw==",
"domain_key": "Pacific",
"view_id": "en_US",
},
"timestamp": 1749545984.2786303
}
}
]
}
Real-time segments
- Real-time segments (RTS) are disabled by default
- You can enable the feature in the snippet configuration object:
cdp_segments: {
rts: true
}
-
cdp_segmentsare attached to the_br_uid_2cookie on the customer domain by JavaScript. -
The
_cdp_segmentscookie is exposed on the customer domain by JavaScript. -
The segments value is refreshed on every page load during tracker start, or when the URL changes (SPA).
-
The segments value is refreshed 5 seconds after tracking any event (post-track refresh).
-
The segments value is refreshed every time the user identity changes.
-
Refreshing of the segments value is asynchronous. Tracking of any event will not wait for the segments request to complete (for example tracking of Discovery page view events will not wait for the latest segments values).
Updated 2 months ago
