Last updated: Aug-31-2023
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.
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.
The interactionAreas object is where you add the relevant configuration allowing you to:
- Define the location of each interaction area using either a template, a vtt file or set manually.
- Add onClick event handlers to enable functionality such as video zoom.
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:
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:
To use a
.vtt file, set the
vttUrl property to the URL of your
.vtt file. For example:
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.
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
zoommethod. 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:
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:
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:
Click the video below to see the UI in action:
|theme||themeProps||The theme settings for the interaction areas.|
|layout||layoutProps||The interaction area UI settings.|
|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:
|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:
|template||String||The template to use for the visual display of the interaction areas. Possible values:
|enable||Boolean||Whether to enable the pre and post roll interaction areas UI. Default:
|showAgain||Boolean||Whether to enable the show again prompt on the pre and post roll interaction areas UI. Default:
|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.,
|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.,
|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.,
|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.,
|id||String||An ID for the area to target when interacting. e.g.,
- Deliver your videos using HLS or DASH adaptive bitrate streaming formats
- Register to events to further customize your player or for analytics tracking
- Check out all the video player options in the Video Player API Reference
- Learn more about the video effects and transformations you can apply to your videos