Viewability

In this topic you will learn about the Brightcove Player viewability feature.

Introduction

The viewability of a player is of fundamental importance to advertising integrations as well as some UI treatments like floating players. In this context, we define “viewability” as the percentage of a player visible in the browser viewport at any given moment. A player is considered “viewable” if some specific percentage of the player is in the viewport.

Brightcove Player 7 introduces viewability tracking DOM events and some valuable behaviors that depend on the player’s viewable state.

Player configuration

The player's viewability events and behavior can be configured in your player's JSON configuration. All configurations are available under the viewability property.

Property Description Type Default
viewability_threshold A number between 0 and 1 representing the portion of the player that must be in the viewport for it to count as "viewable". number 0.6
min_duration_for_viewable_impression Represents the number of milliseconds to wait after ad playback begins before testing for a viewable impression.

By default, this means that the player will report whether the ad impression was viewable using a viewable-ad-impression event after 2 seconds of ad playback.
number 2000
threshold_percentage_increment The amount of viewability change required between viewable-percent-change events.

By default, the value 5 means that viewable-percent-change events will only fire if the viewability of the player has changed by 5% (e.g. from 45% to 50%).

It is recommended not to go any more granular with this as it will fire a lot of events..
number 5
delay_autoplay_if_not_viewable Only interacts with players that are configured for autoplay.

If true, the player delays its playback attempt until the player is viewable.

If false, the player will attempt playback regardless of its viewability state. This is the default behavior of an autoplay player..
boolean false
delay_autoplay_on_mobile_only If true, the delay autoplay feature will only be activated on mobile environments (iOS or Android).

NOTE: In this case, tablets are considered mobile environments..
boolean true
pause_when_not_viewable If true, the player will pause playback if it becomes not viewable. When the player becomes viewable again, playback will resume.

If false, the player will not toggle pause or play on viewable-change. This is the default behavior of a player..
boolean false

Example

Here's the JSON for a player configuration which includes viewability:

{
  ... other properties ...
  "viewability": {
    "viewability_threshold": 0.3,
    "pause_when_not_viewable": true
  }
}

In this example, playback pauses when less than 30% of the player is visible in the browser viewport, caused by the user scrolling the player out of view. Playback resumes when the player becomes visible again.

Viewability events

Users can hook into three new events related to viewability.

  • viewable-change

    This event fires when the player transitions to or from a viewable state.

    Property Type Description
    viewable boolean Represents whether or not the player is in a viewable state
    viewablePercent number Represents the percentage of the player that is currently in the viewport
    Example
    player.on('viewable-change', (e) => {
      if (e.viewable) {
        player.log('the player is viewable!');
      } else {
        player.log('the player is not viewable!');
      }
    });

  • viewable-percent-change

    This event fires when the viewable percentage of the player changes.

    Property Type Description
    viewable boolean Represents whether or not the player is in a viewable state
    viewablePercent number Represents the percentage of the player that is currently in the viewport
    Example
    player.on('viewable-percent-change', (e) => {
      player.log(`the player is ${e.viewablePercent}% viewable!`);
    });

  • viewable-ad-impression

    This event will fire when a viewable ad impression is measured. It will not fire outside the context of ad playback.

    In other words, once an ad has started and played for the number of milliseconds represented by min_duration_for_viewable_impression with the player viewable, this event will fire.

    No additional data is passed with this event.