Continuity Plugin Beta Documentation

Document created by Will Smithee Employee on Dec 4, 2017Last modified by Nic Jansma on Jan 30, 2018
Version 8Show Document
  • View in full screen mode

Original document created by Nic Jansma

 

Note: The Boomerang Continuity plugin is currently in beta. While we don't expect it to cause any issues, beta builds of Boomerang should always be validated on a staging or testing site prior to being used in production.

 

As a consumer of the beta Continuity plugin, we would appreciate your feedback! Please send us any issues or ideas you encounter:

 

boomerang-beta@akamai.com

 

Current Boomerang Continuity Beta: 1.10038.0

 

What is it?

The Continuity plugin is a new Boomerang plugin that measures performance and user experience metrics beyond traditional page load timings.

 

The goal of the Continuity plugin is to capture other important aspects of your visitor's overall experience during page load and beyond. For example, the plugin measures when the site appeared Visually Ready, and when it was Interactive. In addition, the Continuity plugin captures in-page interactions (such as keys, clicks and scrolls), and monitors how the site performed when responding to these inputs. Finally, the Continuity plugin is utilizing cutting-edge browser performance APIs like LongTasks to get amazing insights into how the browser is performing.

 

Here are some of the new metrics being captured:

 

  • New timers:
    • Time to Visually Ready: When did the user feel like they could interact with the site? When did it look ready? (see below for details)
    • Time to Interactive: After the page was Visually Ready, when was the first time the user could have interacted with the site, and had a good (performant) experience? (see below for details)
    • Time to First Interaction: When was the first time the user tried to interact (key, click or scroll) with the site?

  • New interaction metrics:
    • Interactions: keys, clicks, scrolls: counts and event log
    • Delayed Interactions: How often was the user's interaction delayed more than 50ms?
    • Rage Clicks: When the user repeatedly clicked on the same element/region

  • Page performance metrics:
    • Framerate data: FPS during page load, minimum FPS, number of long frames
    • LongTask data: Number of LongTasks, how much time they took, attribution to what caused them

 

In addition to capturing the above metrics during the page load, we're working on the ability to capture many of these metrics whenever the user is interacting with your site after page load (this will incur additional beacons).

Implementation steps

1. Snippet update

The Continuity plugin is currently disabled by default. To enable it for your site, you'll need to use a global BOOMR_config variable to enable it (ideally, right before the Boomerang loader snippet):

 

window.BOOMR_config = {
  Continuity
: {
    enabled
: true,
    waitAfterOnload
: 3000,
    ttiWaitForHeroImages
: ".hero-image"
  
}
};

The waitAfterOnload option will delay the beacon for up to that many milliseconds if Time to Interactive (TTI) doesn't happen by the browser's load event. You shouldn't set it too high, or the likelihood that the page load beacon will be lost increases.

 

If waitAfterOnload is reached and TTI hasn't happened yet, the beacon will be sent immediately (missing the TTI timer).

 

If you set waitAfterOnload to 0 (or it isn't set), Boomerang will send the beacon at the regular page load event. If TTI didn’t yet happen, it won’t be reported.

 

If you want to set waitAfterOnload, we'd recommend between 1000 and 5000 (1 and 5 seconds).

 

2. Create Custom Timers / Metrics

 

The Continuity metrics and timers are not yet available in the mPulse UI. However, you can utilize some of your app's Custom Timers and Custom Metrics to get the Continuity data ingested into the UI.

 

The following fields are all available on the new Continuity plugin. You can report on any of these by creating a Custom Timer or Custom Metric, using JavaScript variable as the source type, and the following strings as the value:

 

Timers:

 

  • BOOMR.plugins.Continuity.metrics.timeToVisuallyReady
    • Time after which we’ll start measuring Time To Interactive
    • This is delayed by any Hero Images or Framework Ready configuration (see below)
  • BOOMR.plugins.Continuity.metrics.timeToInteractive
    • Time to Interactive
  • BOOMR.plugins.Continuity.metrics.timeToFirstInteraction
    • Time to first time the user clicked, keyed or scrolled
  • BOOMR.plugins.Continuity.metrics.longTaskTime
    • Total time of LongTasks on the page (LongTasks are delays over 50ms that the user would’ve felt the browser was unresponsive)
  • BOOMR.plugins.Continuity.metrics.fps
    • Frames Per Second during Page Load
    • Note this will report as “ms” due to a current limitation of our UI, but it’s really Frames Per Second. “30 ms” = “30 FPS”

 

Metrics:

  • BOOMR.plugins.Continuity.metrics.longTasksCount
    • Number of LongTasks reported
  • BOOMR.plugins.Continuity.metrics.scrollCount
    • Number of scroll events
  • BOOMR.plugins.Continuity.metrics.scrollDistinct
    • Number of scrolls that were at least 2 seconds apart from each other
  • BOOMR.plugins.Continuity.metrics.clicksCount
    • Number of mouse clicks
  • BOOMR.plugins.Continuity.metrics.clicksRage
    • Number of “Rage Clicks” where the user clicks the same area or element repeatedly
  • BOOMR.plugins.Continuity.metrics.keyCount
    • Number of keyboard events
  • BOOMR.plugins.Continuity.metrics.fpsLongFrames
    • Number of "long" frames (>18ms)

In addition to the above, there are additional metrics and data being added to the raw (JSON) beacon that will eventually be available in the mPulse UI.

 

3. Controlling Visually Ready via Framework Ready

 

There are two additional options for controlling when Visually Ready happens: via Framework Ready or Hero Images.

 

If you want to wait for your framework to be ready (e.g. your SPA has loaded or the “Bid” button has a click handler registered), you can add an option ttiWaitForFrameworkReady: true:

window.BOOMR_config = {
  Continuity: {
     enabled: true,
     waitAfterOnload: 3000,
     ttiWaitForFrameworkReady: true
  }
};

Once enabled, TTI won’t be calculated until the following is called:

// my framework is ready
BOOMR.plugins.Continuity.frameworkReady();

 

You’ll want to check the existence of BOOMRBOOMR.plugins and BOOMR.plugins.Continuity before calling it, as Boomerang loads async. Once Boomerang loads, it fires the "onBoomerangBeacon" event.

 

4. Controlling Visually Ready via Hero Images

 

If you want to wait for your hero/main images to be loaded before Visually Ready is measured, you can give the plugin a CSS selector via ttiWaitForHeroImages. If set, Visually Ready will be delayed until all IMGs that match that selector have loaded:

window.BOOMR_config = {
  Continuity: {
     enabled: true,
     waitAfterOnload: 3000,
     ttiWaitForHeroImages: ".hero-image"
  }
};

 

Note this only works in ResourceTiming-supported browsers (and won’t be used in older browsers).

5. Request an Upgrade to Beta Continuity

 

Once the above has been configured, you'll need to update your app to a beta build of Boomerang.

 

Please see the Version History (below) for the latest Continuity plugin available, then request an upgrade via support@soasta.com.

 

Implementation Details

Below are details on how Visually Ready (VR) and Time to Interactive (TTI) are calculated.

 

To calculate Time to Interactive, we need to figure out two things:

  • Does the page appear to the visitor to be interactable?
    • We'll use one or more Visually Ready Signals to determine this
  • If so, what's the first time a user could interact with the page and have a good experience?
    • We'll use several Time to Interactive Signals to determine this

 

Visually Ready

 

For the first question, "does the page appear to be interactable?", we need to determine when the page would look to the user like they could interact with it.

 

It's only after this point that TTI could happen. Think of Visually Ready as the anchor point of TTI -- it's the earliest possible timestamp in the page's lifecycle that TTI could happen.

 

We have a few signals that might be appropriate to use as Visually Ready:

  • First Paint (if available)

    • We should wait at least for the first pain on the page
    • i.e. IE's msFirstPaint or Chrome's firstPaintTime
    • These might just be paints of white, so they're not the only signal we should use
  • domContentLoadedEventEnd

    • "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"
    • This happens after domInteractive
    • Available in NavTiming browsers via a timestamp and all other browser if we're on the page in time to listen for readyState change events
  • Hero Images (if defined)

    • Instead of tracking all Above-the-Fold images, it could be useful to know which specific images are important to the site owner
    • Defined via a simple CSS selector (e.g. .hero-images)
    • Can be measured via ResourceTiming
  • "My Framework is Ready" (if defined)

    • A catch-all for other things that we can't automatically track
    • This would be an event or callback from the page author saying their page is ready
    • They could fire this for whatever is imporant to them, i.e. when their page's click handlers have all registered

 

Once the last of all of the above have happened, Visually Ready has occurred.

 

Time To Interactive

 

After the page is Visually Ready for the user, if they were to try to interact with the page (click, scroll, type), when would they have a good experience (i.e. the page responded in a satisfactory amount of time)?

 

We can use some of the signals below, when available:

  • FPS

    • Available in all modern browsers: by using requestAnimationFramewe can get a sense of the overall framerate (FPS)
    • To ensure a "smooth" page load experience, ideally the page should never drop below 20 FPS.
    • 20 FPS gives about 50ms of activity to block the main thread at any one time
  • LongTasks

    • Spec from the W3C
    • Via the PerformanceObserver, fires LongTasks events any time the main thread was blocked by a task that took over 50ms such as JavaScript, layout, etc
    • Great indicator both that the page would not have been interact-able and in some cases, attribution as to why
    • Only available in Chrome
  • Page Busy via setTimeout or requestIdleCallback polling

    • By measuring how long it takes for a regularly-scheduled callback to fire, we can detect other tasks that got in the way
    • Can give an estimate for Page Busy Percentage (%)
    • Available in every browser

 

Algorithm

 

Putting these two together, here's how we measure Visually Ready and Time to Interactive:

  1. Determine the highest Visually Readytimestamp (VRTS):
    1. First Paint (if available)
    2. domContentLoadedEventEnd
    3. Hero Images are loaded (if configured)
    4. Framework Ready (if configured)
  2. After VRTS, calculate Time to Interactiveby finding the first period of 500ms where all of the following are true:
    1. There were no LongTasks
    2. The FPS was always above 20 (if available)
    3. Page Busy was less than 10% (if the above aren't available)

Feedback welcome!

We hope this plugin and new metrics are insightful for you. We’re still experimenting with these metrics and the data collected on our own sites, and hope to adjust them overtime as we get feedback.

 

If you have any questions or concerns, please let us know:

boomerang-beta@akamai.com

 

Version History

  • 1.10033.0: First public beta Continuity plugin
  • 1.10038.0: Second public beta Continuity plugin

Attachments

    Outcomes