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, though if you are using AngularJS, Ember.js or Backbone.js, it is advised to use those specific plugins instead.

The History plugin should be used for React apps.

Note: This plugins requires the BOOMR.plugins.SPA and BOOMR.plugins.AutoXHR plugin as well.

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.


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

If you're using AngularJS, Ember.js or Backbone.js, you are advised to use those plugins instead, as they listen to other app lifecycle events.

For React apps, you should use this plugin (with auto=false mode).

Beacon Parameters

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


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

If you're using a SPA framework that utilizes the window.history object, you should configure it with auto=true. This configures Boomerang to instrument the window.history object, and nothing else needs to be done.

If you are using React, you should configure this plugin with auto=false, and ensure you use the React snippet below. This configures Boomerang to instrument the React-specific history object instead of window.history.

React Configuration

React exposes a history-like object that Boomerang instruments to listen for lifecycle events.

To configure React, you will need to export the history object from React-Router:

import { useBasename } from "history";
import createHashHistory from "history/lib/createHashHistory";
import createBrowserHistory from "history/lib/createBrowserHistory";

var history, hadRouteChange;

// NOTE: Use only one of the two options below

// If the browser supports native HTML5 routing via history:
history = useBasename(createBrowserHistory)({
  basename: location.pathname

// If the browser only supports Hash-based routing:
history = createHashHistory();

After the history variable has been setup, include the following snippet:

function hookHistoryBoomerang() {
  if (window.BOOMR && BOOMR.version) {
    if (BOOMR.plugins && BOOMR.plugins.History) {
      BOOMR.plugins.History.hook(history, hadRouteChange);
    return true;

if (!hookHistoryBoomerang()) {
  if (document.addEventListener) {
    document.addEventListener("onBoomerangLoaded", hookHistoryBoomerang);
  } else if (document.attachEvent) {
    document.attachEvent("onpropertychange", function(e) {
      e = e || window.event;
      if (e && e.propertyName === "onBoomerangLoaded") {



Disables the History plugin


BOOMR.plugins.History The History plugin for chaining


Enables the History plugin


BOOMR.plugins.History The History plugin for chaining

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

Hooks Boomerang into the History events.


Name Type Argument Description
history object

No longer used

hadRouteChange boolean <optional>

Whether or not there was a route change event prior to this hook() call

options object <optional>



BOOMR.plugins.History The History plugin for chaining


Initializes the plugin.


Name Type Description
config object


Name Type Description boolean

Whether or not to automatically instrument the window.history object.

If set to false, the React snippet should be used.


BOOMR.plugins.History The History plugin for chaining


  History: {
    auto: true


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


Type: boolean