Time Engaged Tracking

Note

Time engaged tracking (heartbeat events) is currently not enabled by default. To enable time engaged tracking for your site, please contact support@parsely.com.

New versions of the Parse.ly JavaScript tracker send heartbeat events as well as pageview events to Parse.ly's systems. If enabled, these heartbeat events are sent once every few seconds, providing 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 10.5 seconds, but it can be customized within a range (see below for details).

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 dynamically loaded YouTube videos, with support for other video players planned (including Vimeo and Brightcove). See below for details on video tracking.

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

PARSELY attribute Description
enableHeartbeats If false, do not fire heartbeat events. If true or undefined, fire heartbeat events.
secondsBetweenHeartbeats The number of seconds to wait between sending heartbeat events. Defaults to 10.5. If a number less than 1 or greater than 15 is specified, it is ignored. You may want to increase this number to save battery on mobile devices, for example.
activeTimeout The number of seconds after an interaction event that the user is considered to still be engaged with the webpage. Defaults to 5. If a number less than 1 or greater than 60 is specified, it is ignored.
onHeartbeat A callback function that is called immediately after each heartbeat event is sent. This function has the signature function(engagedSeconds) where engagedSeconds is the number of "engaged seconds" the tracker has counted since the last heartbeat was sent.

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

<script>
    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/Video

For pages that contain 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.

Note

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.