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 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.

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.

Usage

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") {
        hookHistoryBoomerang();
      }
    });
  }
}

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

No longer used

hadRouteChange boolean <optional>

Whether or not there was a route change 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

History.monitorReplaceState boolean <optional>

Whether or not to hook History.replaceState

Returns:

BOOMR.plugins.History The History plugin for chaining

Example

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

is_complete()

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

Returns:

Type: boolean

true