Required events

Required events are the core set of web interactions you must track to give Bloomreach Discovery and Engagement the data they need to personalize search results, power recommendations, and analyze customer behavior. Each event maps to one or more Discovery parameters and is sent to Bloomreach via the Web SDK or the Tracking API.

Event types

Events fall into two categories:

Page view events fire when a page loads, refreshes, or when content changes on a single-page application (SPA).
Interaction events fire on specific user actions, such as clicking a search suggestion or adding an item to the cart.

The table below lists all required events, their category, and the Discovery page type or event type they map to.

Event	Category	Discovery mapping
`view_homepage`	Page view	`ptype=homepage`
`view_category`	Page view	`ptype=category`
`view_item`	Page view	`ptype=product`
`view_search_results`	Page view	`ptype=search`
`view_content`	Page view	`ptype=content`
`view_thematic`	Page view	`ptype=thematic`
`view_other`	Page view	`ptype=other`
`view_quickview`	Page view	`etype=quickview`
`suggest_click`	Interaction	`etype=click`, `group=suggest`
`search_submit`	Interaction	`etype=submit`, `group=suggest`
`cart_update` (add)	Interaction	`etype=click-add`, `group=cart`
`cart_update` (widget add)	Interaction	`etype=cart`
`widget_view`	Interaction	`etype=widget-view`
`widget_click`	Interaction	`etype=widget-click`
`purchase`	Purchase	`ptype=conversion`

Page view events

Track page view events whenever a page loads, refreshes, or in single-page applications when the URL changes and new content renders.

view_homepage

Track this event when the homepage loads.

brweb.track("view_homepage");

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_homepage",
        "properties": {
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

view_category

Track this event on product listing pages and category pages.

brweb.track("view_category", {
  category_id: "650",
  title: "Turtlenecks",
  category_level_1: "Clothes",
  category_level_2: "Sweaters",
  category_level_3: "Sweaters & Cardigans"
});

Event property	Discovery parameter	Notes
`categories_path`	`cat`	Used when `categories_path` contains a vertical bar ( `	` )
`title`	`cat`	Used when `categories_path` does not contain a vertical bar
`category_id`	`cat_id`	—

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_category",
        "properties": {
          "category_id": "650",
          "title": "Turtlenecks",
          "category_level_1": "Clothes",
          "category_level_2": "Sweaters",
          "category_level_3": "Sweaters & Cardigans",
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

view_item

Track this event when a product detail page (PDP) loads. This event records an impression on a product.

brweb.track("view_item", {
  title: "Yellow wide sweater with turtleneck",
  product_id: "119479",
  variant_id: "MJ12199-0400",
  price: 49.99
});

Event property	Discovery parameter
`title`	`prod_name`
`product_id`	`prod_id`
`variant_id`	`sku`

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_item",
        "properties": {
          "title": "Yellow wide sweater with turtleneck",
          "product_id": "119479",
          "variant_id": "MJ12199-0400",
          "price": 49.99,
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

view_search_results

Track this event on search results pages (SRP).

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

Event property	Discovery parameter
`search_term`	`search_term`
`catalogs`	`catalogs`

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_search_results",
        "properties": {
          "search_term": "turtleneck",
          "catalogs": [
            {
              "name": "products_en",
              "view_ids": ["en_US"]
            }
          ],
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

view_content

Track this event when a content item page loads, such as a blog post or article served by Discovery.

brweb.track("view_content", {
  item_id: "article-123",
  title: "How to choose your turtleneck sweater",
  catalogs: [
    {
      name: "content_en",
      view_ids: ["en_US"]
    }
  ]
});

Event property	Discovery parameter
`item_id`	`item_id`
`title`	`item_name`
`catalogs`	`catalogs`

view_thematic

Track this event when a thematic page served by Discovery SEO loads.

brweb.track("view_thematic");

view_other

Track this event on any page that doesn't match one of the page view events above.

brweb.track("view_other");

view_quickview

Track this event when product details appear in a modal on the current page, such as a quickview popup on a product listing page. This event does not trigger a full page load.

brweb.track("view_quickview", {
  title: "Yellow wide sweater with turtleneck",
  product_id: "119479",
  variant_id: "MJ12199-0400"
});

Event property	Discovery parameter
`title`	`prod_name`
`product_id`	`prod_id`
`variant_id`	`sku`

Interaction events

Track interaction events when a user takes a specific action, such as submitting a search query, clicking a suggestion, or updating the cart.

suggest_click

Track this event when a user clicks a suggested item in the search autocomplete — this includes keywords, products, categories, and content suggestions. This event signals intent to search and is deferred to the next page view automatically by the SDK.

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

Event property	Discovery parameter
`q`	`q`
`aq`	`aq`
`catalogs`	`catalogs`

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "suggest_click",
        "properties": {
          "q": "turtleneck",
          "aq": "tur",
          "catalogs": [
            {
              "name": "products_en",
              "view_ids": ["en_US"]
            }
          ],
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US",
          "debug": true,
          "test_data": true
        },
        "timestamp": 1749545984.278
      }
    },
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_search_results",
        "properties": {
          "search_term": "turtleneck",
          "catalogs": [
            {
              "name": "products_en",
              "view_ids": ["en_US"]
            }
          ],
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US",
          "debug": true,
          "test_data": true
        },
        "timestamp": 1749545984.278,
        "deferred_event": {
          "type": "suggest_click",
          "properties": {
            "q": "turtleneck",
            "aq": "tur",
            "catalogs": [
              {
                "name": "products_en",
                "view_ids": ["en_US"]
              }
            ]
          }
        }
      }
    }
  ]
}

search_submit

Track this event when a user submits a search query. This event signals intent to search and is deferred to the next page view automatically by the SDK.

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

Event property	Discovery parameter
`q`	`q`
`catalogs`	`catalogs`

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "search_submit",
        "properties": {
          "q": "turtleneck",
          "catalogs": [
            {
              "name": "products_en",
              "view_ids": ["en_US"]
            }
          ],
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    },
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "cookie": "d218dfa8-37eb-4cd1-aec0-421ad6ccc5c9"
        },
        "event_type": "view_search_results",
        "properties": {
          "search_term": "turtleneck",
          "catalogs": [
            {
              "name": "products_en",
              "view_ids": ["en_US"]
            }
          ],
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278,
        "deferred_event": {
          "type": "search_submit",
          "properties": {
            "q": "turtleneck",
            "catalogs": [
              {
                "name": "products_en",
                "view_ids": ["en_US"]
              }
            ]
          }
        }
      }
    }
  ]
}

cart_update

Track cart_update when a user adds or removes an item from the cart, or adds an item from a widget. The product_list property must always reflect the full contents of the cart after the change — it's a snapshot of the end state, not just the changed item.

📘
Note
Only one item ID can be tracked per event. If a user adds multiple items at once, track a separate cart_update event for each.

Add to cart

Track this when a user adds an item to the cart. This maps to Discovery as an add-to-cart event.

brweb.track("cart_update", {
  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  // in USD reference currency for Engagement
});

Event property	Discovery parameter
`title`	`prod_name`
`product_id`	`prod_id`
`variant_id`	`sku`
`prod_collection_id`	`prod_collection_id`

{
  "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,
          "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

Remove from cart

Track this when a user removes an item from the cart. This event is not sent to Discovery.

brweb.track("cart_update", {
  action: "remove",
  title: "Yellow wide sweater with turtleneck",
  product_id: "119479",
  variant_id: "MJ12199-0400",
  product_list: [
    {
      product_id: "119479",
      quantity: 1
    }
  ],
  total_price: 49.98
});

Add to cart from a widget

Track this when a user adds an item to the cart directly from a Discovery Recommendations or Pathways widget. Include the widget properties alongside the standard cart_update properties.

brweb.track("cart_update", {
  widget_response_id: "abcd123",
  widget_query: "turtleneck",
  widget_id: "asd238",
  widget_type: "mlt",
  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  // in USD reference currency for Engagement
});

Event property	Discovery parameter
`widget_response_id`	`wrid`
`widget_query`	`wq`
`widget_id`	`wid`
`widget_type`	`wty`

widget_view

Track this event when Discovery Recommendations or Pathways widget results are displayed. This event records an impression of the widget.

brweb.track("widget_view", {
  widget_response_id: "abcd123",
  widget_query: "turtleneck",
  widget_id: "asd238",
  widget_type: "mlt"
});

Event property	Discovery parameter
`widget_response_id`	`wrid`
`widget_query`	`wq`
`widget_id`	`wid`
`widget_type`	`wty`

widget_click

Track this event when a user clicks an item in a Discovery Recommendations or Pathways widget.

brweb.track("widget_click", {
  widget_response_id: "abcd123",
  widget_query: "turtleneck",
  widget_id: "asd238",
  widget_type: "mlt",
  item_id: "119479"
});

Event property	Discovery parameter
`widget_response_id`	`wrid`
`widget_query`	`wq`
`widget_id`	`wid`
`widget_type`	`wty`
`item_id`	`item_id`

Purchase events

purchase

Track this event on the order confirmation page when an order is placed. Use purchase_status=created to mark a successful conversion. You can track other statuses — such as paid or return — to record later order lifecycle changes.

Purchase normalization: The system automatically generates individual purchase_item events from each item in product_list. Each item in the list must include product_id and quantity.

🚧
Important
Limitations of purchase events:

product_list supports a maximum of 1,000 line items.

The total event size limit is 800 kB.

If product_list exceeds 1,000 items but is under 800 kB, the event is accepted but individual purchase_item events are not generated. Track these separately if needed.

Tip: Track purchase from the server side if you need to include sensitive data such as costs or margins. See Server-side tracking.

Track a new order

brweb.track("purchase", {
  purchase_id: "ID123",
  purchase_status: "created",
  total_price: 107.72,        // in USD reference currency for Engagement
  local_currency: "EUR",      // display currency for Engagement; used for Discovery currency conversion
  price_local_currency: 99.98,
  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,
      quantity: 2
    }
  ]
});

Event property	Discovery parameter
`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`

{
  "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",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

Track a return

Use negative values for price and quantity to record a return.

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
    }
  ]
});

Automatically added data

The SDK automatically appends the following data to every event. You don't need to include these properties in your brweb.track() calls.

Customer IDs

Property	Description
`$customer_ids.cookie`	Anonymous visitor cookie ID
`$customer_ids.registered`	Registered customer ID (set when `identify` is called without an ID name)

Metadata

Property	Description
`$metadata._br_uid_2`	Bloomreach visitor cookie
`$metadata.domain_key`	Your Discovery catalog key
`$metadata.view_id`	Your Discovery catalog view
`$metadata.debug`	Enables real-time integration mode in Discovery
`$metadata.test_data`	Ignores events in Discovery on production

Event properties

Property	Description
`page_title`	Title of the current page
`location`	Current page URL
`rel_canonical`	Canonical URL of the current page
`referrer`	URL of the referring page
`browser`	User's browser
`device`	User's device type
`os`	User's operating system
`utm_source`	UTM source parameter
`utm_medium`	UTM medium parameter
`utm_campaign`	UTM campaign parameter
`utm_term`	UTM term parameter
`utm_content`	UTM content parameter
`gclid`	Google Click ID
`campaign_id`	Bloomreach campaign ID