If you're new to LUX, make sure to check out our Quick Start Guide. To get even more out of LUX, 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!



LUX is a JavaScript library. LUX works just by loading the lux.js script. Nothing else is needed. But there is a LUX 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 LUX. Since lux.js is loaded asynchronously, use the following pattern to make sure LUX is defined before setting a property:

LUX = window.LUX || {};


If false, the LUX 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 LUX.auto to false, then you need to call LUX.send() in order for the beacon to be sent.


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


This is the “page label” used to group LUX data by page type. The default value is window.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 LUX 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 LUX 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 -> LUX. 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

Since lux.js is loaded asynchronously, you need to make sure these functions are defined before using them. An easy way to do this is to add an onload handler to the lux.js SCRIPT tag, and call the LUX functions inside that handler.

Because LUX.mark and LUX.measure may need to be called before lux.js has loaded, these two functions are defined in the longer snippet. (See the LUX Snippet section.) In other words, if you use LUX.mark or LUX.measure then you should use the longer snippet.

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


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


LUX 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 LUX at the beginning of each SPA "page view" and send the LUX 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, LUX 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 answer your question?