Title: Engaged Time: Setup and tracking options
Author: staff
Published: August 1, 2022
Last modified: November 12, 2025

---

 1. [Installation resources](https://docs.parse.ly/installation-resources/)
 2. [Parse.ly Integration](https://docs.parse.ly/installation-resources/parsely-integration/)
 3. [Tracking code](https://docs.parse.ly/installation-resources/parsely-integration/tracking-code-setup/)
 4. Engaged Time: Setup and tracking options

#  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](https://docs.parse.ly/parsely-integration/).

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](https://docs.parse.ly/parse-ly-video-tracking/-tracking-v2/).
For other video players, you can [manually add support](https://docs.parse.ly/installation-resources/parsely-integration/tracking-code-setup/engaged-time?output_format=md#pages-that-contain-custom-audio-or-video-content).

## 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`.

    ```lang-php
    <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:

    ```lang-php
    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 150. If a number less than the default is specified, it is ignored. You may want to increase this number to save battery on mobile devices. | 
| `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.

    ```lang-php
    <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](https://docs.parse.ly/parse-ly-video-tracking/-tracking-v2/),
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.

    ```lang-php
    <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.

Last updated: November 12, 2025