Skip to content

Embeddable player

The Indee Embeddable Player allows developers embed a secure video player on their website to play Indee video content. This player can be controlled using Javascript API.

The embedded player API (EPAPI) allows the developers to

  1. Initialize the player.
  2. Add event listeners that will execute in response to certain player events, such as a player state change.
  3. Control playback programmatically.
  4. Embed client side watermarking.

This guide explains how to use the API and initialize a new Indee Embeddable Player. It identifies the different types of events that the API can emit and explains how to write event listeners to respond to those events.

Rationale for embeddable player

The decision to develop the Indee Embeddable Player was driven by the need to provide a flexible, secure, and developer-friendly solution for Indee video playback integration. While there are alternative approaches for embedding videos, such as using third-party video players, the embedded player offers several key advantages:

Enhanced Security

By using the Indee Embeddable Player, developers can leverage advanced security features like DRM (Digital Rights Management), token-based authentication, and secure video streaming

Event-Driven Architecture

The API provides event listeners that enable developers to monitor player states, track user interactions, and implement tailored experiences based on playback events.

Consistent User Experience

The embedded player ensures a uniform experience across all platforms and devices, eliminating inconsistencies caused by varying browser or third-party player behaviors.

Implementation Requirements

The browser where you implement the player must support the MessagePort API. Most modern browsers offer full support for this feature. You can use this site to verify compatibility with the target browsers.

Note: Embeddable player doesn't support Firefox playback for as Firefox browser allows the picture-in-picture feature for video players that enables ease of using simple screen capture tools to catpure the video.

Sample Applications

The embeddable player is designed to be compatible with the following JavaScript frameworks and vanilla JavaScript. We have provided sample code for various frameworks for your reference.

Framework Sample Application
Vanilla JS Link
React JS Link
Vue JS Link
Svelte JS Link

Getting Started

HTML Setup

A web page that uses the Embeddable Player API must first load the Indee Embeddable Player Initialization script. This script provides the player initialization function needed to display the player object.

<script src="endpointListing[watch.stream.player_function.retrieve]"></script>

Define the iframe in the HTML Body where you want the embed player to appear:

<iframe id="indee-player" width="800px" height="450px" allow="encrypted-media" allowfullscreen 
referrerpolicy="origin-when-cross-origin" frameborder="0"></iframe>

We recommend using a 16:9 aspect ratio for the Embeddable player Iframe element.

Please note, the iframe will not be rendered until it is initialized, and will not display any placeholder material until that time.

Initializing Embeddable Player

On your webpage you can initialize the player using the following method

initializeIndeePlayer(iframeElementID,playbackData,embeddablePlayerHtml,videoKey,options)

Parameters

  • iframeElementID is the ID of the iframe element the player is to be loaded in
  • playbackData is the data object to initialize the embeddable player. The data object is in the format 
{
    "playbackSourcesData": { 
"drm": "drmObject" , 
"manifest": "manifestObject" 
},
    "playbackMode": "'dash' OR 'hls'",
    "overlayWatermarkDetails": "overlay_watermark_details_Object",
    "savePlayerPreferences": "true OR false",
    "resumeDetails": {
      "from_second": "time_to_resume_from_in_seconds || 0",
      "duration_in_sec": "total_duration_in_seconds"
    },
    "engagementData": {
        "push_interval": "engagement.push_interval",
        "endpointUrl": "endpoints.value['watch.stream.view_engagement.record']"
      }
    }
  • playbackSourcesData : An object constructed using the drm and manifest keys obtained from the Playback API.
  • playbackMode : A string indicating the playback format. It should be HLS on any browser running on the iOS platform and should be DASH all other web browser platforms.
  • overlayWatermarkDetails (optional) : The overlay_watermark_details object retrieved from the Video Details API for the specific video. This ensures that a proper client side overlay watermark is placed on the video automatically if the video has been prepared with a client side watermark.
  • savePlayerPreferences (optional): An optional boolean flag that, when enabled, stores the user's selected audio track and subtitles across different instances of the embeddable player.
  • resumeDetails: An optional object that can be passed to the embeddable player to enable resuming playback from a specific point. This object is constructed using from_second and duration_in_sec, which are available from the Video Details API or Video Listing API. To start playback from the beginning for a particular video, set from_second to 0.
  • engagementData (optional) : The engagementData tracks the user’s engagement with the video such as minutes watched, rewatched etc. This object is created using the push_interval from the Engagement object in the Playback API, along with the endpointUrl, which is obtained by concatenating the host and watch.stream.view_engagement.record from the Endpoint Listing API.

An example playbackData Object

{
    "playbackSourcesData": {
        "drm": {
            "provider": "ezdrm",
            "ceritificate_url": "example.com",
            "license_url": "https://widevine-dash.ezdrm.com/proxy?pX=3B1xxD&sk=W4UHcGauhsZ610qdnFxxIhm-fezUvXWbOy9t041UxxE%3D&server_url=https://api.indee.tv/api/v1/videos/drm/widevine/",
            "token": 12345678,
        },
        "manifest": {
            "url": "example.com",
        }
    },
    "playbackMode": "dash",
    "overlayWatermarkDetails": {
         "text": "b6979d3901",
         "opacity": 60,
         "position": 1,
         "interval_in_seconds": 300,
         "duration_in_seconds": 20,
         "image_link": "https://media.indee.tv/524/video/5766/screener/scn-01hymr1mq2bb2gjvq5fjptq8ehpxvlhv.png?Expires=1734168940&Signature=nW85-SWjwKjWEb8iB4BC4dpddfn9LAvyQd~yXWNBujU9mWxJa4mXTbRgGcvANa5kHR27qT8RvZ2Up0XbOqn8UmwvO~P3qkFZQEsIW0wEs2vutUNzzzEwzYNTwwhPzLS-HRH7vJ9YKzrQaFkgEhWgr2NbeWghCyyWiGPI2HdXOyvEG2pglBxNHG047hkX0sJoIckxlrocB9F~4kNlElgl09um0K1CvMTM1qqlY~4RO8OgsIc5m4VOR7T4xwEWoVG4xMARp9DPKPbxPCT4-x4tjtJHJ6owPEVpAI5rvZNDINNa3jyp-VNqh15rvgvsHdWDLzUb~UGM6NhkT7p69eYM6Q__&Key-Pair-Id=K3HM5NS5Q9EXLB"
    },
    "savePlayerPreferences": true,
    "resumeDetails": {
            "from_second": 12,
            "duration_in_sec": 140
          },
    "engagementData": {
        "push_interval": 30,
        "endpointUrl": "https//:api.indee.tv/v2/watch/stream/view-engagement"
    }
}
  • embeddablePlayerHtml is the HTML data received from watch.stream.player_component.retrieve endpoint to be passed as string.
  • videoKey is the video identifier retrieved from the Video Details API or Video Listing API representing the video to be played in the player
  • options is an optional object that allows for configuring player properties.
    • Options available
      • autoplay: When set to true enables automatic playback of the video without the user clicking on the play button.

Using the parameters provided, calling this function will attempt to initialize the iframe player

Player Listeners APIs

The Player API exposes the ability to listen to various player events on the main HTML page. This allows the page hosting the player to be reactive to video player events. 

listenIndeePlayerState(stateToCapture,cbfunction)
  • stateToCapture is a string parameter that defines the state of the player that you want to listen to. The values that you can provide and listen to are: play, pause, ready, complete.
  • cbfunction is the callback function that is triggered when the event you requested in "stateToCapture" value occurs.

An example of how to register a listener for play click events on the player:

window.listenIndeePlayerState("play", (args1,args2) => {
   functionName(args1, args2);
});

Note : This function can only be used when the window is loaded. Its behavior is not guaranteed if it is not loaded during the window load time. If a front end framework is used, this function should be called during in the framework’s mounted lifecycle hook