Guide
TrainingSupportCommunity

Single page apps

Suggest Edits

📘

As of Boomerang version 1.681.0, AngularJS, Backbone.js, Ember.js and React framework specific setup is not required.

For Boomerang versions 1.672.0 and below, please see the legacy framework specific plugins documentation here

Why

Boomerang monitors Single Page App (SPA) navigations differently than how it monitors navigations on traditional websites. SPA frameworks such as AngularJS, Backbone.js, Ember.js, React, etc. are supported.

On traditional websites, the browser completes a full navigation for every page. During this navigation, the browser requests the page's HTML, JavaScript, CSS, etc., from the server, and builds the page from these components.
Boomerang monitors this entire process.

On SPA websites, only the first page that the visitor loads is a full navigation. All subsequent navigations are handled by the SPA framework itself (i.e. AngularJS), where they dynamically pull in the content they need to render the new page. This is done without executing a full navigation from the browser's point of view.

Boomerang was designed for traditional websites, where a full navigation occurs on each page load. During the navigation, Boomerang tracks the performance characteristics of the entire page load experience. However, for SPA websites, only the first page triggers a full navigation. Thus, without any additional help, Boomerang will not track any subsequent interactions on SPA websites.

The History boomerang plugin instruments calls and monitors events from the browser's History API. API calls such as pushState, replaceState, etc. and events such as hashchange and popstate are used to track the SPA navigations beyond the first, initial navigation. Once boomerang detects these events, the Boomerang SPA plugins start monitoring the page's markup (DOM) for changes. If any of these changes trigger a download, such as a XHR, image, CSS, or JavaScript, then the Boomerang SPA plugins monitor those resources as well. Only once all of these new resources have been fetched do the Boomerang SPA plugins consider the SPA navigation complete.

For more information, see How mPulse XMLHttpRequest (XHR) and Single Page Application (SPA) Monitoring works.

If you are collecting ResourceTiming data in your SPA app, please also see how to manage the ResourceTiming buffer.

Terminology

  • Hard Navigation: the first navigation to the site, plus any of the work required to build the initial view. The Hard Navigation will track at least the length of onload​, but may also include the additional time required to load the framework (for example, Angular) and the first view. A SPA site will only have a SPA Hard Navigation, no "Page Load" beacons.
  • Soft Navigation: any navigation after the first Hard Navigation. A soft navigation is an "in-page" navigation where the view changes, but the browser does not actually fully navigate.

Metrics and sessions

Page Groups, Custom Timers, Custom Metrics and Custom Dimensions are tracked on SPA websites the same way as on traditional websites (e.g. using XPath, Regex, JavaScript variables, cookies, CSS, etc).

Sessions are also tracked the same way as on traditional websites. The session length will increase every time the route (address bar) changes, and the session will be kept alive as long as user actions occur.

Configuration Options

The Boomerang History plugin allows users to automatically monitor Single Page App's (SPA) navigations beyond the initial page load for SPA frameworks that leverage the window.history object for keeping state and routing (eg. AngularJS, Backbone.js, Ember.js, React, etc.).

For SPA frameworks that use window.history, all you have to do is to add the standard mPulse loader snippet, and check the Enable Single Page App (SPA) Monitoring feature in the mPulse Configure Web App dialog box under Single Page Application Framework.

Page-Level Override for Partial SPA Sites

If your website includes both SPA and non-SPA pages, page-level overrides ensure the SPA pages still track performance data.

If all of your pages are SPA:

  1. Check the Enable Single Page App (SPA) Monitoring checkbox in the mPulse Configure Web App dialog box.
  2. Insert the standard mPulse Loader Snippet.

If most of your pages are SPA:

  1. Check the Enable Single Page App (SPA) Monitoring checkbox in the mPulse Configure Web App dialog box.
  2. Insert the standard mPulse Loader Snippet.
    Add the following snippet on non-SPA pages:
window.BOOMR_config = window.BOOMR_config || {};
BOOMR_config.autorun = true;
BOOMR_config.History = {
    enabled: false
};

If only one or a few of your pages are SPA:

  1. Uncheck the Enable Single Page App (SPA) Monitoring checkbox in the mPulse Configure Web App dialog box.
  2. Insert the standard mPulse Loader Snippet.
  3. Add the following snippet on SPA pages:
window.BOOMR_config = window.BOOMR_config || {};
BOOMR_config.autorun = false;
BOOMR_config.History = {
    enabled: true
};

Excluding certain requests from instrumentation

Whenever Boomerang intercepts an XMLHttpRequest, it will check if that request matches anything in the Boomerang XHR excludes list (BOOMR.xhr_excludes). If it does, Boomerang will not instrument, time, or beacon that request. If the excluded XHR happens during a SPA navigation, Boomerang will not track that
XHR for purposes of extending the SPA navigation.

The exclude list is defined by creating an xhr_excludes object under the global window.BOOMR object, and adding in the URL parts that you would like to exclude from instrumentation. You can put any of the following in it:

  1. A full HREF
  2. A hostname
  3. A path

Example

BOOMR = window.BOOMR || {};

BOOMR.xhr_excludes = {
  "www.soasta.com":  true,
  "c.go-mpulse.net": true,
  "/api/v1/foobar":  true,
  "https://mpulse.soasta.com/dashboard/": true
};

In the above example, Boomerang will skip instrumentation for:

  • All URLs under www.soasta.com and c.go-mpulse.net
  • All URLs that exactly match the path /api/v1/foobar (regardless of the
    hostname or query string parameters)
  • The exact URL https://mpulse.soasta.com/dashboard/

Note that all of the above are exact matches (you cannot include wildcards).

Updated almost 2 years ago