Getting started with the SpeedCurve RUM JavaScript API (lux.js)

If you're new to RUM, make sure to check out our RUM getting started guide
To get even more out of RUM, read our API below, which explains how to:

  • adjust your sample rate

  • add customer data (such as cart size and conversion rate)

  • add page labels, so you can compare synthetic and RUM data

  • monitor SPAs

  • add custom timers

  • and more!

Note: "LUX" refers to the SpeedCurve RUM JavaScript library lux.js.


RUM works just by loading the lux.js script. Nothing else is needed. But there is an API that provides additional features as described here. All of the API is accessed through the LUX global variable.

LUX Properties

You can set these properties to alter the default behavior of RUM. Since lux.js is loaded asynchronously, use the following pattern to make sure LUX is defined before setting a property:

LUX = window.LUX || {};

If set to false, the beacon is not sent at the window load event. The default value is true. The reason for setting this to false is if your page is a template and the actual content is loaded after the window load event, or something else happens after the onload that you want included in the beacon. If you set to false, then you need to call LUX.send() in order for the beacon to be sent.


LUX = window.LUX || {}; = false;


If set to true, debug messages are written to the browser console. Debug messages indicate things like:

  • when lux.js is loaded

  • whether the current session is sampled

  • if the Long Task API and Paint Timing API are supported

  • the user timing and customer data values that are set

Also see LUX.getDebug().


LUX = window.LUX || {}; 
LUX.debug = true;


This is the “page label” used to group RUM data by page type. The default value is the current page title (taken from document.title). It’s a best practice to set pages to the same label used in your SpeedCurve synthetic Settings for the same page type. Maximum length is 255 characters.


LUX = window.LUX || {};
LUX.label = 'home';


This is the sample rate for determining whether the beacon is sent. You can set it to an integer from 0 to 100 inclusive as the percentage of metrics to accept. This is useful for collecting data while staying under your RUM budget of page views per month. The percentage is based on the session ID, therefore, entire sessions are accepted or rejected in whole.

A simpler way to control your sample rate is to specify it under Settings -> RUM. But you can use LUX.samplerate to have more fine-grained control (such as setting different sample rates for different countries, pages, devices, etc.).


LUX = window.LUX || {};
LUX.samplerate = 10; // 10% of metrics are accepted

LUX Functions

LUX.addData(name, value)

This function is used to add your own custom data to the beacon. This "customer data" can be used in the SpeedCurve UI to segment the RUM performance data. This is useful for doing A/B testing. You can also store business metrics (e.g., cart size or conversions) and plot those along with performance metrics to see correlations. The maximum allowable size of all name value pairs concatenated is 255 characters. See Customer Data for more information.


LUX.addData('cartsize', 128);
LUX.addData('experiment A', 'control');


This function is incredibly handy if you have set a RUM sample rate and are trying to debug RUM on your site. Imagine that your sample rate is 1% and you're loading one of your pages in the browser to see whether RUM data is generated. 99% of the time no RUM data is generated, but you won't know if that's because RUM isn't working or you're not being sampled.

In RUM, sampling is based on your session cookie. So the only way to make sure you get sampled is to change your cookie. Calling LUX.forceSample() changes your session cookie so that on all subsequent page views you will be sampled and should see RUM data being generated. Note that session cookies expire after 24 hours or 30 minutes of inactivity, so you might have to call LUX.forceSample() again.


Sampling has been turned on for this session.


Setting the LUX.getDebug() flag in your RUM snippet causes debug messages to be written to console. But in some situations there's a desire to see the debug messages without having to make a code change to your site. Calling LUX.getDebug() returns the debug messages in an array. If you're experiencing problems getting RUM working on your site, a first step is to call LUX.getDebug() in the browser console to get more insight into what is, and is not, happening. Also see LUX.debug and LUX.forceSample().


(23) ["lux.js evaluation start.", ...


RUM works automatically for normal ("Web 1.0") pages. But if your site is a Single Page App (SPA) then you need to add code to initialize RUM at the beginning of each SPA "page view" and send the beacon at the end. Call this function at the beginning of the SPA page transition.


// start SPA page transition


This function is identical to performance.mark from the User Timing spec for marking a specific time milestone in the page. It's provided as a shim for browsers that don't support the User Timing spec, most notably Safari. Maximum length for markName is 128 characters.


LUX.mark("before JSON");

LUX.measure(name, startMark, endMark)

This function is identical to performance.measure from the User Timing spec for measuring the delta between two time milestones in the page. It's provided as a shim for browsers that don't support the User Timing spec, most notably Safari. Maximum length for name is 128 characters.


LUX.measure("JSON request", "before JSON");


This function is used along with LUX.init for SPA sites.


// end of SPA page transition

LUX HTML Attributes


When the first interaction with the page is a click or key press, RUM tracks which DOM element was interacted with. The name that is recorded is based on searching the DOM element and its ancestors for the data-sctrack attribute. If data-sctrack is not found, then the first DOM element ID is used.

Example: If the user clicked on any of these links, then "navbar" would be tracked as the DOM element the user interacted with.

<div data-sctrack="navbar">
    <li> <a href="/" id=home>Home</a>
    <li> <a href="/shop" id=shop>Shop</a>
    <li> <a href="/search" id=search>Search</a>

Did this page help you?