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.

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

History object

hadRouteChange boolean <optional>

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

options object <optional>

Options

Returns:

BOOMR.plugins.History The History plugin for chaining


init(config)

Initializes the plugin.

Parameters:

Name Type Description
config object

Configuration

Properties
Name Type Description
History.auto boolean

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

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

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