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 API

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 || {};

LUX.auto

If set to 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.

Example:

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

LUX.debug

If set to true, LUX 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().

Example:

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

LUX.label

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.

Example:

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

LUX.samplerate

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

Example:

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. See LUX Customer Data for more information.

Example:

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

LUX.forceSample()

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

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

Example:

LUX.forceSample()
Sampling has been turned on for this session.

LUX.getDebug()

Setting the LUX.debug flag in your LUX 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 LUX 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().

Example:

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

LUX.init()

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.

Example:

LUX.init();
// start SPA page transition

LUX.mark(markName)

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.

Example:

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.

Example:

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

LUX.send()

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

Example:

// end of SPA page transition
LUX.send();

LUX HTML Attributes

data-sctrack

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">
  <ul>
    <li> <a href="/" id=home>Home</a>
    <li> <a href="/shop" id=shop>Shop</a>
    <li> <a href="/search" id=search>Search</a>
  </ul>
</div>
Did this answer your question?