Viewability

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
`pause_in_background_tab`	If true, the player will automatically be paused when the browser tab is in the background.	`boolean`	`false`
`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`
`pause_on_blur`	If `true`, the player will automatically pause when a user navigates away from the browser window to focus on another app.	`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.

The frequency of this event can be influenced by the threshold_percentage_increment configuration, but it can fire quite often. This means performing any computationally expensive operation on this event could degrade performance.

The recommendation is to use it only if it's really needed. Most use-cases just want to know when the player moves to or from a viewable state and should use the viewable-change event.

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