Extending KDP: Guide to creating Flash (AS3) based KDP Modules

KDP - Dynamic Player and Playlist Widget
[Hide Book Menu]

Mon, 09/07/2009 - 20:28 — Kalturian

This guide refers only to KDP version 2.5 and 2.6.

For first time integration, please read this Playback Guide first.

Download the KDP Flash Module Sample Kit.

Introduction

The KDP provides an API that enables to extend its features via run-time loaded Flash Modules.
A KDP Flash Module is compiled swf file written in ActionScript 3 for the Flash Player 9 and above.
The KDP Flash Module can be compiled using Adobe Flash IDE (CS3 and above), Adobe Flash Builder (or Flex Builder), FlashDevelop or any other Flash Compiler capable of producing Flash 9 and above SWF files.

See a demo of play/pause button and Google Analytics flash modules.

Modules Anatamoy of KDP - Introduction to Modules

The KDP is an Adobe Flex 3 based application that makes an extensive use of the Flex Modules.
Every component of the KDP is written as a module. There is a long list of modules available in the KDP project, some are being compiled as part of the main application and the rest are being loaded at run-time. Here are a few of the available modules:

KplayerModule - The module that is responsible for playback of media assets (image, video, audio, mixes).
Scrubber and Progress bar.
Gigya - A third party module by Gigya that provides share, distribute and track the KDP widget across the web and via email, the module loads the official Gigya widget to be used in the KDP. This module utilize the KDP architecture to provide the "Share Button" feature, load the gigya widget and uses the KDP uiConf to customize (change style, layout and features) the gigya widget.
Timer and total time - A module that presents the current playhead time and the time left till the end of the video. This module uses the KDP architecture to catch the events describing the playhead progress, and the duration of the played media. The time module also make use of the KDP uiConf to customize it's style and behavior.
VolumeBar - A vertical volume slider and mute/unmute button, that control the volume of the played media.
Adap-Tv Module - Commercial third party layer that provides ad integration for pre-roll, mid-roll, overlays and post-roll ads. This module load the Adap-Tv widget at run-time and integrates between the KDP APIs and the loaded Adap-Tv widget.

The above modules are created as Flex Modules, and can be compiled using the Adobe Flex Compiler released as part of the Open Source Adobe Flex SDK.

KDP Flash Module - Background

The KDP Flash Module is a Flex Module that loads a compiled SWF Flash application at run-time and provides an interface for the KDP APIs.
It forms an integration level for Flash based application that doesn't have to be compiled using the Flex SDK.
The Flash module was created mainly for the following reasons -

To lower the bar for new KDP modules development - Creating a KDP Flash Module doesn't require the KDP Flex project or Adobe Flex SDK on your system. Download the sample kit, make sure your Flash application implements the interface (2 functions) and you'r good to go. To test it, load your module to a compiled KDP using FlashVars or modified uiConf (read ahead learn more).
Flash is more Flexible - Flex is a complicated, highly customizable RIA framework. However, sometimes all you need is the paintbrush and a few lines of code - and Flex would be an overhead. Using the KDP Flash Module, your Flash application will be loaded to the KDP and integrate with it's features, seamlessly.

Step 1 - Download the Sample Kit

The Sample Kit include a folder that contains the following:

kdp-Flashmodule.php - A demo php file to be run on the localhost as testing environment.
kdp_Flash_module_sdk - A folder that contains the KDP Module API and two sample projects.
PlayPauseKdpFlashmodule.swf - A compiled sample module that provide a Play and Pause toggle button on top of the video area.
KdpGoogleAnalyticsmodule.swf - A compiled sample module that provides Google Analytics tracking of the KDP events.

Step 2 - Compile a KDP Flash module

To easily get started the Kit provide two sample modules -

PlayPauseKdpFlashmodule - A module that provide a Play and Pause toggle button on top of the video area.
KdpGoogleAnalyticsmodule - A module that provides Google Analytics tracking of the KDP events.

To compile the modules, open the respected fla file from the kdp_Flash_module_sdk folder, and compile (hit Ctrl+Enter).

Step 3 - Load the KDP Flash module into KDP

There are two ways of loading the created KDP Flash module to the KDP.

Modifying the uiConf.
Using FlashVars (Only for pre-defined uiConfs).

Loading KDP Flash module by modifying the uiConf

To define a new KDP Flash module on the uiConf you should edit the uiConf and add one of the following lines:

<Module k_path="addons/KdpSwfWrapper.swf" height="0" width="0" id="ga" k_swf_url="kdp_ga.swf" k_params="ga_id:UA-8888-0"/>
- The element is <Module>
- The attribute k_path="addons/KdpSwfWrapper.swf" should always remain the same
- Set width and height by changing the values from 0, if this is a non-visual module, set these to 0
- The attribute id should be unique through the rest of the uiConf
- The attribute k_swf_url should direct to the full url of the module swf file
- The attribute k_params should contain any additional parameters to pass to the module, formatted by key1:value1,...,keyN:valueN
<Module k_path="addons/KdpSwfWrapper.swf" height="0" width="0" id="kdpSwfModule" k_fv_url="pd_KdpSwfUrl" />
All should remain the same, with the following addition:
Set the k_fv_url attribute to the name of the FlashVar parameter that its value is the module url

To update the uiConf you can use the api_v3: uiConf.add, uiConf.get and uiConf.update services.

Loading KDP Flash module using FlashVars

If the KDP uiConf have a KDP Flash module module definition, it is possible to load a Flash module via HTML Object FlashVars.

Use the name of the moduleUrl as it is stated in the uiConf k_fv_url attribute and set its value to the url of the KDP Flash module to load
To pass additional parameters to the KDP Flash module, use the following format in FlashVars: pd_{module_k_fv}_{param}, for example: pd_swfModule_ga_id=UA-7714780-1, where swfModule is the name of the module.
- pd_ - should always remain as the preceding part
- {module_k_fv} - the uiConf k_fv_url attribute value, removing the "url" from the end
- {param} - the parameter name to pass to the KDP Flash module (this is the name of the parameter the KDP Flash module expect to receive).

Refer to the kdp-Flashmodule.php sample for working example.

The anatomy of a KDP Flash module

KDP provide a mediator Flex module that enable to load and interact with Flash only based swf files.
However, in order to provide access to the KDP functionality and events, the created Flash module should implement the ISWFModule interface.
The ISWFModule interface declare a single function: registerManager(dispatcher:EventDispatcher, params:Object):void
The registerManager function is infact the single connection that is initiated by the KDP to the Flash module, the function is being immidiately after the flash module was fully loaded, initialized and added to the stage. The registerManager function provides the following two parameters:

dispatcher - This is the KDP Manager, the singleton that is responsible to orchastrate and notify about the various actions and events occuring inside the KDP.
Use the dispatcher object to listen to the KDP events or to dispatch events and perform actions.
Use the CommandEvents class to learn about the events the KDP may dispatch or receive.
Use the KalturaStatsEventType class to learn what statistics the KDP is notifying about, every statistics event is dispached with an StatsEvent object that contains additional information about the event the statistics is about.
params - this is an object that include all parameters passed to the Flash module via uiConf or flashVars.

State awareness and ad modules

See various advertising KDP modules in action.
Ads (Commercials) require state awareness, to achieve the three different ad types: pre, post and mid rolls (overlay doesn't require more than playback progress).
To orchestrate the various states and manage cases where multiple ad modules are used, the KDP use a chain of custom defined events described in the uiConf, several static state events and current state flag.
The current state can be retrieved by accessing the manager.kdpModel.kdpState variable (read only).
The states that are available are listed in the KdpPlayerStates class (com.kaltura.kdp.managers.KdpPlayerStates).
The following code snippet shows a way in which we can identify the KDP is currently plays a preroll (before the actual media plays) -

If (manager.kdpModel.kdpState == KdpPlayerStates.PRE_MEDIA_STATE) {

        trace ("KDP is now playing the PRE roll ad");

}

Accessing specific UI component in run-time

To retrieve reference to a specific UI element in the KDP, use the manager['getComponentById']() function.
getComponentById, will return a specific UIComponent given its id as defined in the uiConf XML.
The following code snippet shows a way to retrieve the url of the media that is currently being played.
To get the url of the media, we first need to access the media object.
To get the media object, we need to access the player component that holds the media object.
We use the getComponentById function on the KDP manager to retrieve access to the player using its id as defined in the uiConf XML ('myKplayer').
Then, we access the kalturaEntry object that represent the media currently being played, the kalturaEntry object holds the dataUrl – the url of the media.

trace ('The currently playing media URL is: ' + manager['getComponentById']('myKplayer').kalturaEntry.dataUrl);