BOOMR


boomerang measures various performance characteristics of your user's browsing experience and beacons it back to your server.

To use this you'll need a web site, lots of users and the ability to do something with the data you collect. How you collect the data is up to you, but we have a few ideas.

Everything in boomerang is accessed through the BOOMR object, which is available on window.BOOMR. It contains the public API, utility functions (BOOMR.utils) and all of the plugins (BOOMR.plugins).

Each plugin has its own API, but is reachable through BOOMR.plugins.

Beacon Parameters

The core boomerang object will add the following parameters to the beacon.

Note that each individual plugin will add its own parameters as well.

  • v: Boomerang version
  • sv: Boomerang Loader Snippet version
  • sm: Boomerang Loader Snippet method
  • u: The page's URL (for most beacons), or the XMLHttpRequest URL
  • n: The beacon number
  • pgu: The page's URL (for XMLHttpRequest beacons)
  • pid: Page ID (8 characters)
  • r: Navigation referrer (from document.location)
  • vis.pre: 1 if the page transitioned from prerender to visible
  • vis.st: Document's visibility state when beacon was sent
  • vis.lh: Timestamp when page was last hidden
  • vis.lv: Timestamp when page was last visible
  • xhr.pg: The XMLHttpRequest page group
  • errors: Error messages of errors detected in Boomerang code, separated by a newline
  • rt.si: Session ID
  • rt.ss: Session start timestamp
  • rt.sl: Session length (number of pages), can be increased by XHR beacons as well
  • ua.plt: navigator.platform or if available navigator.userAgentData.platform
  • ua.arch: navigator userAgentData architecture, if client hints requested
  • ua.model: navigator userAgentData model, if client hints requested
  • ua.pltv: navigator userAgentData platform version, if client hints requested
  • ua.vnd: navigator.vendor

Classes

Members


boomerang_frame :Window

The Boomerang frame:

  • If Boomerang was loaded in an IFRAME, this is the IFRAME
  • If Boomerang was loaded inline, this is the current window

Type:

  • Window

boomr.t_lstart :TimeStamp

Time the loader script started fetching boomerang.js (if using the asynchronous loader snippet) (BOOMR_lstart)

Type:


boomr.t_onload :TimeStamp

Time the window.onload event fired (if using the asynchronous loader snippet).

This timestamp is logged in the case boomerang.js loads after the onload event for browsers that don't support NavigationTiming.

Type:


config_url :string

(Optional) URL of configuration file

Type:

  • string

lastVisibilityEvent :object

An mapping of visibliity event states to the latest time they happened

Type:

  • object

loadedLate :boolean

Whether or not Boomerang was loaded after the onload event.

Type:

  • boolean

t_end :TimeStamp

When the Boomerang plugins have all run.

This value is generally set in zzz-last-plugin.js.

Type:


t_start :TimeStamp

The timestamp when boomerang.js showed up on the page.

This is the value of BOOMR_start we set earlier.

Type:


url :string

URL of boomerang.js.

Type:

  • string

version :string

Boomerang version, formatted as major.minor.patchlevel.

This variable is replaced during build (grunt build).

Type:

  • string

window :Window

The main document window.

  • If Boomerang was loaded in an IFRAME, this is the parent window
  • If Boomerang was loaded inline, this is the current window

Type:

  • Window

xhr_excludes

URLs to exclude from automatic XMLHttpRequest instrumentation.

You can put any of the following in it:

  • A full URL
  • A hostname
  • A path

Example

BOOMR = window.BOOMR || {};
BOOMR.xhr_excludes = {
  "mysite.com": true,
  "/dashboard/": true,
  "https://mysite.com/dashboard/": true
};

Methods


addError(err [, src] [, extra])

Logs an internal Boomerang error.

If the BOOMR.plugins.Errors plugin is enabled, this data will be compressed on the err beacon parameter. If not, it will be included in uncompressed form on the errors parameter.

Parameters:

Name Type Argument Description
err string | object

Error

src string <optional>

Source

extra object <optional>

Extra data


addVar(name [, val] [, singleBeacon])

Add one or more parameters to the beacon.

This method may either be called with a single object containing key/value pairs, or with two parameters, the first is the variable name and the second is its value.

All names should be strings usable in a URL's query string.

We recommend only using alphanumeric characters and underscores, but you can use anything you like.

Values should be strings (or numbers), and have the same restrictions as names.

Parameters will be on all subsequent beacons unless singleBeacon is set. Early beacons will not clear vars that were set with singleBeacon.

Parameters:

Name Type Argument Default Description
name string | object

Variable name

val string | object <optional>

Value. If the first parameter is an object, this becomes the singleBeacon parameter.

singleBeacon boolean <optional>
false

Whether or not to add to a single beacon or all beacons.

Returns:

Type: BOOMR

Boomerang object

Example

BOOMR.addVar("page_id", 123);
BOOMR.addVar({"page_id": 123, "user_id": "Person1"});

appendVar(name, val)

Appends data to a beacon.

If the value already exists, a comma is added and the new data is applied.

Parameters:

Name Type Description
name string

Variable name

val string

Value

Returns:

Type: BOOMR

Boomerang object


attach_page_ready(cb)

Attach a callback to the pageshow or onload event if onload has not been fired otherwise queue it to run immediately

Parameters:

Name Type Description
cb function

Callback to run when onload fires or page is visible (pageshow)


debug(m [, s])

Logs debug messages to the console

Debug messages are stripped out of production builds.

Parameters:

Name Type Argument Description
m string

Message

s string <optional>

Source


disable()

Disables boomerang from doing anything further:

  1. Clears event handlers (such as onload)
  2. Clears all event listeners

error(m [, s])

Logs error messages to the console

Parameters:

Name Type Argument Description
m string

Message

s string <optional>

Source


fireEvent(e_name, data)

Fires a Boomerang event

Parameters:

Name Type Description
e_name string

Event name

data object

Event payload

Returns:

Type: BOOMR

Boomerang object


forceSameSiteCookieNone()

Allows us to force SameSite=None from a Boomerang plugin or a third party code.

When this function is called then Boomerang won't honor "same_site_cookie" configuration key and won't attempt to return the default value of SameSite=Lax .


getPerformance()

Gets the window.performance object of the root window.

Checks vendor prefixes for older browsers (e.g. IE9).

Returns:

Type: Performance | undefined

window.performance if it exists


getResourceTiming(url [, sort] [, filter])

Gets the latest ResourceTiming entry for the specified URL.

Default sort order is chronological startTime.

Parameters:

Name Type Argument Description
url string

Resource URL

sort function <optional>

Sort the entries before returning the last one

filter function <optional>

Filter the entries. Will be applied before sorting

Returns:

Type: PerformanceEntry | undefined

Entry, or undefined if ResourceTiming is not supported or if the entry doesn't exist


getUriEncodedVar(name, value)

Gets a URI-encoded name/value pair.

Parameters:

Name Type Description
name string

Name

value string

Value

Returns:

Type: string

URI-encoded string


getVar(name)

Gets the specified variable.

Parameters:

Name Type Description
name string

Variable name

Returns:

Type: object | undefined

Variable, or undefined if it isn't set


getVarsOfPriority(vars, pri)

Gets all variables of the specified priority

Parameters:

Name Type Description
vars object

Variables (will be modified for pri -1 and 1)

pri number

Priority (-1, 0, or 1)

Returns:

Type: Array.<string>

Array of URI-encoded vars


hasSentPageLoadBeacon()

Determines whether or not a Page Load beacon has been sent.

Returns:

Type: boolean

True if a Page Load beacon has been sent.


hasVar(name)

Determines whether or not the beacon has the specified variable.

Parameters:

Name Type Description
name string

Variable name

Returns:

Type: boolean

True if the variable is set.


info(m [, s])

Logs info messages to the console

Parameters:

Name Type Argument Description
m string

Message

s string <optional>

Source


init(config [, ])

Initializes Boomerang by applying the specified configuration.

All plugins' init() functions will be called with the same config as well.

Parameters:

Name Type Argument Description
config object

Configuration object

Properties
Name Type Argument Description
autorun boolean <optional>

By default, boomerang runs automatically and attaches its page_ready handler to the window.onload event. If you set autorun to false, this will not happen and you will need to call BOOMR.page_ready yourself.

beacon_auth_key string

Beacon authorization key value

beacon_auth_token string

Beacon authorization token.

beacon_with_credentials boolean

Sends beacon with credentials

beacon_disable_sendbeacon boolean

Disables navigator.sendBeacon() support

beacon_url string

The URL to beacon results back to. If not set, no beacon will be sent.

beacon_url_force_https boolean

Forces protocol-relative Beacon URLs to HTTPS

beacon_type string

GET, POST or AUTO

site_domain string <optional>

The domain that all cookies should be set on Boomerang will try to auto-detect this, but unless your site is of the foo.com format, it will probably get it wrong. It's a good idea to set this to whatever part of your domain you'd like to share bandwidth and performance measurements across. Set this to a falsy value to disable all cookies.

strip_query_string boolean <optional>

Whether or not to strip query strings from all URLs (e.g. u, pgu, etc.)

user_ip string <optional>

Despite its name, this is really a free-form string used to uniquely identify the user's current internet connection. It's used primarily by the bandwidth test to determine whether it should re-measure the user's bandwidth or just use the value stored in the cookie. You may use IPv4, IPv6 or anything else that you think can be used to identify the user's network connection.

same_site_cookie string <optional>

Used for creating cookies with SameSite with one of the following values: None, Lax or Strict.

secure_cookie boolean <optional>

When true all cookies will be created with Secure flag.

request_client_hints boolean <optional>

When true, gather high entropy values for Architecture, Model and Platform data from navigator.userAgentData.

no_unload boolean <optional>

Disables all unload handlers and the Unload beacons

log function <optional>

Logger to use. Set to null to disable logging.

function <optional>

Each plugin has its own section

Returns:

Type: BOOMR

Boomerang object


instrumentFetch()

Instrument all requests made via fetch to send beacons.

This is implemented in plugins/auto-xhr.js BOOMR.plugins.AutoXHR.


instrumentXHR()

Instrument all requests made via XMLHttpRequest to send beacons.

This is implemented in plugins/auto-xhr.js BOOMR.plugins.AutoXHR.


isCrossOriginError(err)

Determines if the specified Error is a Cross-Origin error.

Parameters:

Name Type Description
err string | object

Error

Returns:

Type: boolean

True if the Error is a Cross-Origin error.


log(m, l [, s])

Logs the message to the console

Parameters:

Name Type Argument Description
m string

Message

l string

Log level

s string <optional>

Source


now()

Gets the current time in milliseconds since the Unix Epoch (Jan 1 1970).

In browsers that support DOMHighResTimeStamp, this will be replaced by a function that adds performance.now() to navigationStart (with milliseconds.microseconds resolution).

Returns:

Type: TimeStamp

Milliseconds since Unix Epoch


onloadFired()

Determines whether or not the page's onload event has fired, or if autorun is false, whether BOOMR.page_ready was called.

Returns:

Type: boolean

True if onload or BOOMR.page_ready were called


page_ready( [ev], auto)

Method that fires the BOOMR#event:page_ready event. Call this only if you've set autorun to false when calling the BOOMR.init method. You should call this method when you determine that your page is ready to be used by your user. This will be the end-time used in the page load time measurement. Optionally, you can pass a Unix Epoch timestamp as a parameter or set the global BOOMR_page_ready var that will be used as the end-time instead.

Parameters:

Name Type Argument Description
ev Event | number <optional>

Ready event or optional load event end timestamp if called manually

auto boolean

True if called by page_ready_autorun

Returns:

Type: BOOMR

Boomerang object

Example

BOOMR.init({ autorun: false, ... });
// wait until the page is ready, i.e. your view has loaded
BOOMR.page_ready();

page_ready_autorun(ev)

Sends the page_ready event only if autorun is still true after BOOMR.init is called.

Parameters:

Name Type Description
ev Event

Event


readyToSend()

Determines if Boomerang can send a beacon.

Queryies all plugins to see if they implement readyToSend(), and if so, that they return true.

If not, the beacon cannot be sent.

Returns:

Type: boolean

True if Boomerang can send a beacon


real_sendBeacon()

Sends all beacon data.

This function should be called directly any time a "new" beacon is about to be constructed. For example, if you're creating a new XHR or other custom beacon, you should ensure the existing beacon data is flushed by calling BOOMR.real_sendBeacon(); first.


registerEvent(e_name)

Registers a Boomerang event.

Parameters:

Name Type Description
e_name string

Event name

Returns:

Type: BOOMR

Boomerang object


removeVar(name)

Removes one or more variables from the beacon URL. This is useful within a plugin to reset the values of parameters that it is about to set.

Plugins can also use this in the BOOMR#event:beacon event to clear any variables that should only live on a single beacon.

This method accepts either a list of variable names, or a single array containing a list of variable names.

Parameters:

Name Type Description
name Array.<string> | string

Variable name or list

Returns:

Type: BOOMR

Boomerang object


requestStart(name)

Starts a timer for a dynamic request.

Once the named request has completed, call loaded() to send a beacon with the duration.

Parameters:

Name Type Description
name string

Timer name

Returns:

Type: object

An object with a .loaded() function that you can call when the dynamic timer is complete.

Example

var timer = BOOMR.requestStart("my-timer");
// do stuff
timer.loaded();

responseEnd(name, t_start, data, t_end)

Sends a beacon for a dynamic request.

Parameters:

Name Type Description
name string | object

Timer name or timer object data.

Properties
Name Type Argument Description
initiator string <optional>

Initiator, such as xhr or spa

url string <optional>

URL of the request

t_start TimeStamp

Start time

data object

Request data

t_end TimeStamp

End time


sendAll(data)

Sends a set of Custom Metrics and Timers immediately

Parameters:

Name Type Description
data object

An object containing a map of Custom Metrics, Timers and other variables

Properties
Name Type Argument Description
metrics object <optional>

Custom Metrics

timers object <optional>

Custom Timers

vars object <optional>

Additional beacon parameters

when object <optional>

Timestamp for the event

Example

BOOMR.sendAll({
  metrics: {
    conversion: 1,
    size: 1000
  },
  timers: {
    customTimer1: 125
  },
  vars: {
    var1: 1,
    var2: 2
  },
  when: 9999999
});

sendBeacon( [beacon_url_override])

Request boomerang to send its beacon with all queued beacon data (via BOOMR.addVar).

Boomerang may ignore this request.

When this method is called, boomerang checks all plugins. If any plugin has not completed its checks (ie, the plugin's is_complete() method returns false, then this method does nothing.

If all plugins have completed, then this method fires the BOOMR#event:before_beacon event with all variables that will be sent on the beacon.

After all BOOMR#event:before_beacon handlers return, this method checks if a beacon_url has been configured and if there are any beacon parameters to be sent. If both are true, it fires the beacon.

The BOOMR#event:beacon event is then fired.

sendBeacon() should be called any time a plugin goes from is_complete() = false to is_complete = true so the beacon is sent.

The actual beaconing is handled in BOOMR.real_sendBeacon after a short delay (via BOOMR.setImmediate). If other calls to sendBeacon happen before BOOMR.real_sendBeacon is called, those calls will be discarded (so it's OK to call this in quick succession).

Parameters:

Name Type Argument Description
beacon_url_override string <optional>

Beacon URL override


sendMetric(name [, value])

Sends a Custom Metric immediately

Parameters:

Name Type Argument Description
name string

Metric name

value number <optional>

Metric value (1 if not specified)

Examples

BOOMR.sendMetric("conversion");
BOOMR.sendMetric("size", 1000);

sendMetrics(metrics)

Sends a set of Custom Metrics immediately

Parameters:

Name Type Description
metrics object

An object containing Custom Metric names and values

Examples

BOOMR.sendMetrics({ "conversion": 1 });
BOOMR.sendMetrics({ "conversion": 1, "size": 1000 });

sendTimer(name, value)

Sends a Custom Timer immediately

Parameters:

Name Type Description
name string

Timer name

value number

Timer value

Example

BOOMR.sendTimer("customTimer1", 125);

sendTimers(timers)

Sends a set of Custom Timers immediately

Parameters:

Name Type Description
timers object

An object containing Custom Timer names and values

Example

BOOMR.sendTimers({ "customTimer1": 125 });

sendXhrPostBeacon(xhr [, paramsJoined])

Sends a beacon via XMLHttpRequest

Parameters:

Name Type Argument Description
xhr object

XMLHttpRequest object

paramsJoined object <optional>

XMLHttpRequest.send() argument


setImmediate(fn [, data] [, cb_data] [, cb_scope])

Defer the function fn until the next instant the browser is free from user tasks.

Parameters:

Name Type Argument Description
fn BOOMR~setImmediateCallback

The callback function.

data object <optional>

Any data to pass to the callback function

cb_data object <optional>

Any passthrough data for the callback function. This differs from data when setImmediate is called via an event handler and data is the Event object

cb_scope object <optional>

The scope of the callback function if it is a method of an object

Returns:

nothing


setReferrer(r)

Sets the Referrers variable.

Parameters:

Name Type Description
r string

Referrer from the document.referrer


setVarPriority(name, pri)

Sets a variable's priority in the beacon URL. -1 = beginning of the URL 0 = middle of the URL (default) 1 = end of the URL

Parameters:

Name Type Description
name string

Variable name

pri number

Priority (-1 or 1)

Returns:

Type: BOOMR

Boomerang object


subscribe(e_name, fn, cb_data, cb_scope, once)

Subscribes to a Boomerang event

Parameters:

Name Type Description
e_name string

Event name, i.e. BOOMR#event:page_ready.

fn BOOMR~subscribeCallback

Callback function

cb_data object

Callback data, passed as the second parameter to the callback function

cb_scope object

Callback scope. If set to an object, then the callback function is called as a method of this object, and all references to this within the callback function will refer to cb_scope.

once boolean

Whether or not this callback should only be run once

Returns:

Type: BOOMR

Boomerang object


uninstrumentFetch()

Undo fetch instrumentation and reset the original fetch function

This is implemented in plugins/auto-xhr.js BOOMR.plugins.AutoXHR.


uninstrumentXHR()

Undo XMLHttpRequest instrumentation and reset the original XMLHttpRequest object

This is implemented in plugins/auto-xhr.js BOOMR.plugins.AutoXHR.


visibilityState()

Gets the document.visibilityState, or visible if Page Visibility is not supported.

Returns:

Type: string

Visibility state


warn(m [, s])

Logs warning messages to the console

Parameters:

Name Type Argument Description
m string

Message

s string <optional>

Source

Type Definitions


addObserverCallback(mutations, callback_data)

The callback function may return a falsy value to disconnect the observer after it returns, or a truthy value to keep watching for mutations. If the return value is numeric and greater than 0, then this will be the new timeout. If it is boolean instead, then the timeout will not fire any more so the caller MUST call disconnect() at some point.

Parameters:

Name Type Description
mutations Array.<object>

List of mutations detected by the observer or undefined if the observer timed out

callback_data object

Is the passed in callback_data parameter without modifications


setImmediateCallback(data, cb_data, callstack)

The callback function may return a falsy value to disconnect the observer after it returns, or a truthy value to keep watching for mutations. If the return value is numeric and greater than 0, then this will be the new timeout. If it is boolean instead, then the timeout will not fire any more so the caller MUST call disconnect() at some point

Parameters:

Name Type Description
data object

The passed in data object

cb_data object

The passed in cb_data object

callstack Error

An Error object that holds the callstack for when setImmediate was called, used to determine what called the callback


subscribeCallback(eventData, cb_data)

Parameters:

Name Type Description
eventData object

Event data

cb_data object

Callback data

Events


beacon

Boomerang event, subscribe via BOOMR.subscribe.

Fired when a beacon was sent.

The beacon variables cannot be modified at this point. Any calls to BOOMR.addVar or BOOMR.removeVar will apply to the next beacon.

Also known as onbeacon.

Properties:

Name Type Description
vars object

Beacon variables


before_beacon

Boomerang event, subscribe via BOOMR.subscribe.

Fired when a beacon is about to be sent.

The subscriber can still add variables to the beacon at this point, either by modifying the vars paramter or calling BOOMR.addVar.

Properties:

Name Type Description
vars object

Beacon variables


before_early_beacon

Boomerang event, subscribe via BOOMR.subscribe.

Fired when an early beacon is about to be sent.

The subscriber can still add variables to the early beacon at this point by calling BOOMR.addVar.

This event will only happen if BOOMR.plugins.Early is enabled.

Properties:

Name Type Description
data object

Event data


before_unload

Boomerang event, subscribe via BOOMR.subscribe.

Fired before the document is about to be unloaded.

window.beforeunload will trigger this.

See:


bfcache

Boomerang event, subscribe via BOOMR.subscribe.

Fired when an BFCache navigation occurs.

The subscriber can still add variables to the BFCache beacon at this point by calling BOOMR.addVar.

This event will only happen if BOOMR.plugins.BFCache is enabled.

Properties:

Name Type Description
data object

Event data


click

Boomerang event, subscribe via BOOMR.subscribe.

Fired when the click event has happened on the document.

See:


config

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever new configuration data is applied via BOOMR.init.

Also known as onconfig.

Properties:

Name Type Description
data object

Configuration data


dom_loaded

Boomerang event, subscribe via BOOMR.subscribe.

Fired on document.DOMContentLoaded.

The DOMContentLoaded event is fired when the initial HTML document has been completely loaded and parsed, without waiting for stylesheets, images, and subframes to finish loading

See:


error

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever a page error has happened.

This event will only happen if BOOMR.plugins.Errors is enabled.

Also known as onerror.

Properties:

Name Type Description
err object

Error


form_submit

Boomerang event, subscribe via BOOMR.subscribe.

Fired when any FORM element is submitted.

See:


netinfo

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever connection information changes via the Network Information API.

This event will only happen if BOOMR.plugins.Mobile is enabled.

Properties:

Name Type Description
connection object

navigator.connection


page_load_beacon

Boomerang event, subscribe via BOOMR.subscribe.

Fired when the page load beacon has been sent.

This event should only happen once on a page. It does not apply to SPA soft navigations.

Properties:

Name Type Description
vars object

Beacon variables


page_ready

Boomerang event, subscribe via BOOMR.subscribe.

Fired when the page is usable by the user.

By default this is fired when window.onload fires, but if you set autorun to false when calling BOOMR.init, then you must explicitly fire this event by calling BOOMR#event:page_ready.

Properties:

Name Type Argument Description
event Event <optional>

Event triggering the page_ready

See:


page_unload

Boomerang event, subscribe via BOOMR.subscribe.

Fired just before the browser unloads the page.

The first event of window.pagehide, window.beforeunload, or window.unload will trigger this.

See:


prerender_to_visible

Boomerang event, subscribe via BOOMR.subscribe.

Fired when the visibilityState of the document has changed from prerender to visible

See:


rage_click

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever a Rage Click is detected.

This event will only happen if BOOMR.plugins.Continuity is enabled.

Properties:

Name Type Description
e Event

Event


spa_cancel

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever a SPA navigation is cancelled.


spa_init

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever a SPA plugin is about to track a new navigation.

Properties:

Name Type Description
parameters Array.<object>

Navigation type (spa or spa_hard), URL and timings


spa_navigation

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever a SPA navigation is complete.

Properties:

Name Type Description
parameters Array.<object>

Timings


visibility_changed

Boomerang event, subscribe via BOOMR.subscribe.

Fired on document.visibilitychange.

The visibilitychange event is fired when the content of a tab has become visible or has been hidden.

See:


xhr_error

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever and XMLHttpRequest has an error (if its status is set).

This event will only happen if BOOMR.plugins.AutoXHR is enabled.

Also known as onxhrerror.

Properties:

Name Type Description
data object

XHR data


xhr_init

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever XMLHttpRequest.open is called.

This event will only happen if BOOMR.plugins.AutoXHR is enabled.

Properties:

Name Type Description
type string

XHR type ("xhr")


xhr_load

Boomerang event, subscribe via BOOMR.subscribe.

Fired when an XMLHttpRequest has finished, or, if something calls BOOMR.responseEnd.

Properties:

Name Type Description
data object

Event data


xhr_send

Boomerang event, subscribe via BOOMR.subscribe.

Fired whenever XMLHttpRequest.send is called.

This event will only happen if BOOMR.plugins.AutoXHR is enabled.

Properties:

Name Type Description
xhr object

XMLHttpRequest object