Programmable Media

Interactive Video (Beta)

Last updated: Sep-12-2024

Important
Interactive video functionality is currently in Beta. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

You can use interactive videos to define a set of interaction areas on the player, allowing users to interact with your videos to trigger additional functionality. Some examples of how this could be used are:

  • Zooming in on areas of a video by switching the source to a zoomed version.
  • Linking the user to a specific web page related to the content.
  • Opening a dialogue box or triggering other functionality.

Adding interaction areas

To add interactivity to your videos, you need to add a set of interaction areas to your video player. This is done by adding the interactionAreas object when setting the video source.

Module imports
To use interaction areas when importing the player as a module, you also need to import the interaction-areas module. For example:

The interactionAreas object is where you add the relevant configuration allowing you to:

You can also Configure the interactive videos UI to suit your use case.

Before adding your interaction areas, ensure you have set up your video player code as described in how to embed the video player, here's a basic example:

Using a template

To set the interaction areas using a template, first enable the interaction areas by adding the interationAreas parameter and setting the enable property to true, and the template property to either 'portrait', 'landscape', 'all', or 'center'. The templates define the locations for the areas using a .vtt file. You can use one of the following example files as a basis for creating your own vtt file:

  • portrait defines 3 areas positioned in a vertical line.
  • landscape defines 3 areas positioned in a horizontal line.
  • all defines 1 area that is clickable across the whole video.
  • center defines 1 area positioned centrally.

You can also include the onClick event handler to handle the behavior when an interactionArea is clicked. For example:

Using a vtt file

To use a .vtt file, set the vttUrl property to the URL of your .vtt file. For example:

You can find example .vtt files in the template section and more information about the parameters used in the .vtt file in the manualInteractionAreaProps table of the reference.

Defining the areas manually

To set your interaction areas manually, set the value of the template property to an array of manualInteractionArea objects. This allows you to define the location for each of the interaction areas you need.

Here's a full example of passing the interactionAreas object when setting the video player source:

See the manualInteractionAreaProps table in the reference for more information on the parameters used.

Video zoom

One of the main use cases for interactive videos is to allow users to zoom in on a video. Zooming can be achieved in two ways, both of which use the zoom method as an onClick event for an interaction area.

  • For basic zooming that provides a standard digitally zoomed in view of the video, call the method with no additional options.
  • For more advanced zooming, you can provide different video sources as an option when calling the zoom method. The different sources can be enhanced high quality videos to provide a richer experience. You can set the additional sources as an object as shown in the example below.

Click the video below to see the UI in action:


Here's an example of the required configuration for basic zooming functionality:

Note
When embedding the video player scripts directly on your page, the interactive videos functionality is lazily loaded. As a result, the interactionDisplay parameter is required when initializing the player. The parameter is used for customizing the UI, but can also just be set to true, for example:

Here's an example of the configuration required for the more advanced zoom functionality. The sources defined here match the IDs defined in the template vtt file and are used to switch to the right source on click:

Here's the full code required for the example above:

Configuring the interactive video UI

The UI that is enabled when using interactive videos can be configured to match your requirements by defining your options as part of the interactionDisplay constructor parameter. You can set:

  • The theme options to use for the interaction areas themselves. You can define the template to use, where the possible options are 'pulsing' (default) or 'shadowed'
  • The layout options to use for the UI when the player loads. You can define whether you want to enable the UI overlay and whether to display the show again prompt.

Here's an example of the configuration used to change the interaction areas to be shadowed and to enable the show again prompt:

Code explorer: Video interactivity

The React example below demonstrates the full code required to implement interactive videos and includes both video zoom functionality as well as a simple JavaScript alert.

Click the video below to see the UI in action:

This code is also available in GitHub.

Tip
Enjoy interactive learning? Check out more code explorers!

Reference

Player parameters

interactionDisplay

Param Type Description
theme themeProps The theme settings for the interaction areas.
layout layoutProps The interaction area UI settings.

Source parameters

interactionAreas

Param Type Description
enable Boolean Whether to enable interaction areas. Required to enable the functionality.
template String or array of manualInteractionAreaProps The template name to use or an array of manually defined interaction areas. Possible values: portrait, landscape, all, center.
vttUrl String URL The URL of a vtt file defining the required interaction areas.
onClick Function The function that is called when clicking an interaction area.
syncOffsetTime Boolean Whether to synchronize the interactive area videos to start playing from the same offset (point in time) as the original video, or from the beginning of the video. Useful when the original and interactive area video are the same content and zoomed in. Note that the result can become unpredictable if the durations of the videos are not identical. Default: false

Types

themeProps

Param Type Description
template String The template to use for the visual display of the interaction areas. Possible values: pulsing, shadowed. Default: pulsing

layoutProps

Param Type Description
enable Boolean Whether to enable the pre and post roll interaction areas UI. Default: true
showAgain Boolean Whether to enable the show again prompt on the pre and post roll interaction areas UI. Default: false

manualInteractionAreaProps

Param Type Description
left Number Offset location from the left as a percentage of the remaining width of the video (once the width of the interaction area has been subtracted) e.g., 10
top Number Offset location from the top as a percentage of the remaining height of the video (once the height of the interaction area has been subtracted) e.g., 10
width Number The width of the interaction area as a percentage of the video. The icon to indicate the area will not increase in width. e.g., 80
height Number The height of the interaction area as a percentage of the video. The icon to indicate the area will not increase in height. e.g., 40
id String An ID for the area to target when interacting. e.g., topSource

✔️ Feedback sent!

Rate this page: