Tracking on single-page applications (SPAs)

In a traditional multi-page website, the browser loads a new HTML document on every page navigation. This gives the Bloomreach Web SDK a natural trigger (the page load) to fire tracking events. Single-page applications (SPAs) work differently. The browser loads the application once, and subsequent navigation updates the DOM without a full page reload. Without special handling, the SDK would only track the initial page load and miss all subsequent navigation.

The SDK handles this automatically. It observes URL changes (including hash changes) and fires the appropriate tracking events without any extra configuration on your part.

How SPA tracking works

When the SDK detects a URL change, it treats the navigation as a new page view and fires the relevant default tracking events, such as page_visit, if visits tracking is enabled in your configuration. It also updates two key event properties automatically:

• referrer is set to the URL of the previous page (URL before the navigation occurred).
• location is set to the URL of the current page (the URL after the navigation occurred).

These properties map directly to Discovery parameters:

This means Discovery receives the correct page context on every navigation, without you needing to manage URL tracking manually in most cases.

Configure SPA behavior

You can customize how the SDK handles SPA navigation using the spa_reloading object in your configuration. Pass it inside the configuration object when you call brweb.start().

brweb.start({
  // ... your other config ...
  spa_reloading: {
    enabled: true,         // enable or disable SPA tracking (default: true)
    track_visited_pages: true  // re-track events when revisiting a URL within the session
  }
});

For the full list of SDK configuration options, see JS SDK configuration.

Track page views without a URL change

SPA tracking relies on URL changes to detect navigation. When content updates without a URL change, for example, when a visitor applies a search filter or changes the sort order on a product listing page, the SDK has no signal to fire a new page view event. In these cases, you need to track the event manually.

The best approach is to update the URL when filter or sort state changes. This keeps tracking automatic and keeps your URL state shareable and bookmarkable. If updating the URL isn't possible, track the page view event manually using brweb.track() and pass explicit location and referrer values to override the SDK defaults.

In this example, a visitor applies a color filter on a search results page. The URL doesn't change, so the event is tracked manually:

brweb.track("view_search_results", {
  search_term: "turtleneck",
  catalogs: [
    {
      name: "products_en",
      view_ids: ["en_US"]
    }
  ],
  referrer: "https://www.pacific.com/en/catalogsearch/result?q=turtleneck",
  location: "https://www.pacific.com/en/catalogsearch/result?q=turtleneck&colors=Beige"
});

📘

Note

When you pass referrer and location manually, they override the SDK-generated values for that event only. All other automatically added properties such as page_title, lang, browser, and device are still appended by the SDK.

{
  "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"]
            }
          ],
          "location": "https://www.pacific.com/en/catalogsearch/result?q=turtleneck&colors=Beige",
          "referrer": "https://www.pacific.com/en/catalogsearch/result?q=turtleneck",
          "page_title": "Pacific | Clothing & accessories",
          "lang": "en-US",
          "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
      }
    }
  ]
}

Reload weblayers on navigation

When the SDK detects a URL change in a SPA, it does not automatically reload weblayers. This means a weblayer triggered on one page continues to display after the visitor navigates to a different page, unless you reload it explicitly.

To reload weblayers after a navigation event, call brweb.reloadWebLayers() in your router's navigation handler:

// example using a generic router navigation hook
router.afterEach(() => {
  brweb.reloadWebLayers();
});

This tells the SDK to re-evaluate weblayer display conditions against the current page context and visitor state, ensuring the right weblayer appears on each page.