mPulse Boomerang

BOOMR.plugins. History

The History plugin allows you to automatically monitor Single Page App (SPA) navigations that change their routes via the window.history object.

The History plugin can be used for any SPA (eg. Angular, Backbone, Ember, React, Vue, etc.) and replaces the deprecated Angular, Backbone and Ember plugins.

Note: This plugin requires the BOOMR.plugins.AutoXHR and BOOMR.plugins.SPA plugins to be loaded first (in that order).

For details on how Boomerang Single Page App instrumentation works, see the BOOMR.plugins.SPA documentation.

For information on how to include this plugin, see the Building tutorial.

Compatibility

This plugin should work with any Single Page App, by instrumenting the window.history object to monitor for route changes.

The SPA app needs to change the history state or hash before doing the work required to change the route (eg. XHRs, DOM node changes). With frameworks where the history events happen after the route change has completed (e.g. Ember.js 1.x), we can configure the plugin with monitorHistory: false and call BOOMR.plugins.SPA.route_change() manually when the route change begins.

Beacon Parameters

This plugin does not add any additional beacon parameters beyond the BOOMR.plugins.SPA plugin.

Usage

Include the BOOMR.plugins.AutoXHR, BOOMR.plugins.SPA and BOOMR.plugins.History plugins. See Building for details.

Methods

disable()

Disables the History plugin

Returns:

BOOMR.plugins.History The History plugin for chaining

enable()

Enables the History plugin

Returns:

BOOMR.plugins.History The History plugin for chaining

hook(history [, hadRouteChange] [, options])

Hooks Boomerang into the History events.

Parameters:

Name Type Argument Description
history object

Deprecated
hadRouteChange boolean <optional>

Deprecated event prior to this hook() call
options object <optional>

Optional options. Can contain routeFilter and/or routeChangeWaitFilter

Returns:

BOOMR.plugins.History The History plugin for chaining

init(config)

Initializes the plugin.

Parameters:

Name Type Description
config object

Configuration

Properties
Name Type Argument Description
History.auto boolean <optional>

Whether or not to automatically instrument the window.history object. If set to false, the React snippet should be used.
History.disableHardNav boolean <optional>

Whether or not to disable SPA hard beacons
History.routeFilter function <optional>

Route change filter callback function
History.routeChangeWaitFilter function <optional>

Route change wait filter callback function. This is called on each route change, and if returns true, Boomerang will wait for a BOOMR.plugins.SPA.wait_complete() call before marking a navigation complete. By default, this only applies to SPA Soft navigations.
History.routeChangeWaitFilterHardNavs boolean <optional>

Whether to apply wait filter on hard navs. If set to true, the routeChangeWaitFilter function will apply to SPA hard navigations in addition to soft navigations.
History.monitorReplaceState boolean <optional>

Whether or not to hook History.replaceState

Returns:

BOOMR.plugins.History The History plugin for chaining

Examples

Basic

BOOMR.init({
  History: {
    enabled: true
  }
});

With routeChangeWaitFilter and routeChangeWaitFilterHardNavs

BOOMR.init({
  History: {
    enabled: true,
    routeChangeWaitFilter: function() {
      if (window.location.href.indexOf("route-that-needs-to-wait/") !== -1) {
        // You're telling Boomerang that in addition to the standard SPA heuristics,
        // Boomerang should additionally wait for your application to call this API:
        //
        //   BOOMR.plugins.SPA.wait_complete();
        //
        return true;
      }

      // You're telling Boomerang that the standard SPA heuristics will be applied to this
      // route, no custom endpoint is needed. BOOMR.plugins.SPA.wait_complete()
      // should not be called.
      return false;
    },
    routeChangeWaitFilterHardNavs: true
  }
});

is_complete()

This plugin is always complete (ready to send a beacon)

Returns:

Type: boolean

true