Interactive Video (Beta)

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 can be done in two ways:

  • Setting global interactionAreas for your video player instance using the interactionAreas constructor parameter.
  • Defining the areas per video by adding the interactionAreas object when setting the source.

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

Before adding your interaction areas, ensure you have set up your video player code as described in how to embed the video player, and you will also need to set the bigPlayButton constructor parameter to false. Here's a basic example:

Copy to clipboard
<video
  id="player"
  controls
  muted
  class="cld-video-player">
</video>
Copy to clipboard
var cld = cloudinary.Cloudinary.new({cloud_name: 'demo'});
var player = cld.videoPlayer('player',{
          bigPlayButton: false
      });

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:

Copy to clipboard
interactionAreas: {
    enable: true,
    template: 'portrait', // or landscape/all/center,
    onClick: function(event) {
        // Code for event here 
    }
}

Using a vtt file

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

Copy to clipboard
interactionAreas: {
    enable: true,
    vttUrl: 'https://res.cloudinary.com/prod/raw/upload/video-player/vtts/center.vtt',
    onClick: function(event) {
        // Code for event here 
    }
}

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:

Copy to clipboard
player.source('docs/my_video', {
        interactionAreas: {
          enable: true,
          template: [
            {
                left : 10 ,
                top: 10,
                width: 80,
                height: 40,
                id: 'topSource'
            },
            {
                left : 10 ,
                top: 75,
                width: 80,
                height : 20,
                id: 'bottomSource'
            }
          ],
          onClick: function(event) {
            // Code for event here 
          }
        }
});

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:

Copy to clipboard
player.source('docs/my_video', {
  interactionAreas: {
      enable: true,
      template: 'portrait',
      onClick: function(event) {
          event.zoom(); 
      }
  }
});

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:

Copy to clipboard
var sources = {
        top:'https://res.cloudinary.com/demo/video/upload/docs/my_video_top_zoom.mp4',
        middle:'https://res.cloudinary.com/demo/video/upload/docs/my_video_middle_zoom.mp4',
        bottom:'https://res.cloudinary.com/demo/video/upload/docs/my_video_bottom_zoom.mp4'
      }

player.source('my_video', {
  interactionAreas: {
      enable: true,
      template: 'portrait',
      onClick: function(event) {
          event.zoom(sources[event.item.id]); 
      }
  }
});

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

Copy to clipboard
<video
  id="player"
  width="250"
  controls
  muted
  class="cld-video-player">
</video>
Copy to clipboard
var cld = cloudinary.Cloudinary.new({cloud_name: 'demo'});

var player = cld.videoPlayer('player',{
          bigPlayButton: false
      });

var sources = {
        top:'https://res.cloudinary.com/demo/video/upload/docs/my_video_top_zoom.mp4',
        middle:'https://res.cloudinary.com/demo/video/upload/docs/my_video_middle_zoom.mp4',
        bottom:'https://res.cloudinary.com/demo/video/upload/docs/my_video_bottom_zoom.mp4'
      }

player.source('my_video', {
  interactionAreas: {
      enable: true,
      template: 'portrait',
      onClick: function(event) {
          event.zoom(sources[event.item.id]); 
      }
  }
});

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 interactionAreas 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:

Copy to clipboard
cld.videoPlayer('player', {
  interactionAreas: {
      theme:{
        template : 'shadowed'
      },
      layout: {
          enable: true,
          showAgain: true
      }
  }
});

Reference

interactionAreas

Param Type Description
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 but can be used to override the globally set default at source level.
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.

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: