Engaged Time: Setup and tracking options

When time engaged tracking is enabled (it’s enabled by default), the Parse.ly JavaScript tracker sends heartbeat events as well as pageview events to Parse.ly’s systems. Heartbeat events provide Parse.ly’s systems information about how much time users spend “engaged” with a given page.

Once Parse.ly support has enabled time engaged heartbeats, no further changes are needed to your integration. Simply include the JavaScript tracker on your site as detailed in the basic tracking section.

A heartbeat event is nearly identical to the standard Parse.ly pageview pixel request. The only difference is that the action parameter automatically sent to Parse.ly is set to heartbeat, and the request includes an additional parameter inc that is used to indicate the amount of time engaged that has elapsed since the last heartbeat was sent.

Definition

Parse.ly defines time engaged with the following formula:

video playing OR (interacted recently AND window in focus)

That is, a user is said to be “engaged” with a webpage if a video is playing, or if the webpage is in focus and the user has interacted with the page recently.

The time engaged tracker is constantly evaluating the above formula. It notes how long there has been engagement with the page and sends Parse.ly’s systems a number indicating that length of time every few seconds. By default, this timeout is set to 150 seconds, but it can be customized within a range (see below for details). Note that if a user navigates away from the page or closes their browser before the 150-second mark, a heartbeat is sent with the accumulated engaged time..

The Parse.ly bundle tracks interaction by listening to a number of common browser events that indicate movement on the page: click, scroll, mouseup, mousedown, focus, touchstart, touchend, and many more.

The time engaged bundle currently supports a number of common video players automatically. For other video players, you can manually add support.

Enabling and Disabling Heartbeats

Once Parse.ly support has enabled time engaged heartbeats, the Parse.ly bundle will send heartbeats by default. In cases where you want a page to track pageviews but not time engaged, you can disable the heartbeat events by setting PARSELY.enableHeartbeats to false.

<script>
  window.PARSELY = window.PARSELY || {
    // other configuration options...
    enableHeartbeats: false
  };
</script>

<!-- START Parse.ly Include -->
<!-- ...insert the parsely tracker code here... -->
<!-- END Parse.ly Include -->

You can also disable heartbeat events after the initial load of the PARSELY object with:

window.PARSELY.enableHeartbeats = false;

Configuration Options

The time engaged JavaScript bundle supports a few configuration options that let you customize your integration based on your needs. All of the following configuration attributes are optional.

Here is an example demonstrating each of these configuration attributes in use.

<script>
  window.PARSELY = window.PARSELY || {
    // other configuration options...

    // ensure heartbeat events are enabled
    enableHeartbeats: true,

    // set time between heartbeat events
    secondsBetweenHeartbeats: 15,

    // set time after interaction that user is considered "unengaged"
    activeTimeout: 3,

    // when a heartbeat event is sent, call this function
    onHeartbeat: function(engagedSeconds) {
      console.log("The user was engaged for " + engagedSeconds + " seconds.");
    },

    // other configuration options...
  };
</script>

<!-- START Parse.ly Include -->
<!-- ...insert the parsely tracker code here... -->
<!-- END Parse.ly Include -->

Pages That Contain Audio or Video Content

For video players automatically detected by the Parse.ly tracker, no additional integration is necessary.

Otherwise, for pages that contain non-supported audio or video content, the time engaged tracker needs to be informed of when A/V is playing on the page for the most accurate tracking of time spent. This is because it is common for users to click “play” on A/V content and then not perform any mouse or keyboard actions in the browser while they listen to or watch the content.

For this use case, you can use the videoPlaying attribute to track the time any audio or video content starts / stops playing on a given page.

<script>
  $("#myVideo").on('custom_video_started_playing', function() {
    if (window.PARSELY) {
      PARSELY.videoPlaying = true;
    }
  });
  $("#myVideo").on('custom_video_stopped_playing', function() {
    if (window.PARSELY) {
      PARSELY.videoPlaying = false;
    }
  });
</script>

The above code assumes you’ve created custom JavaScript events that fire when your custom video player pauses and unpauses a video. When these events are triggered, you can set PARSELY.videoPlaying to indicate that the tracker should gather engagement data throughout the period, even if there is a lack of other explicit user actions.

It is critical that you test PARSELY.videoPlaying transitions to ensure they cover edge cases. The last thing you want is for all of your “time spent” calculations to be inflated because the Parse.ly tracker thinks your A/V content is “always playing” even when it’s not.