Creating KDP Plugins

This guide will walk you through the steps to create KDP 3.x plugins.
To learn how to set up the Flash Builder with the KDP3 project, refer to this guide.

Starting KDP version 3.0.0 and above, KDP is built in AS3 only and is not based on the Flex framework. This enables easier & faster deployment and smaller file sizes. This is also why Flex modules are no longer supported and only AS3 based plugins can be used.

The last step - a KDP3 plugin definition on the layout document (uiConf)

KDP 3 plugins are defined by the <Plugin /> tag.
This tag dictates to KDP3 to load an external .swf file at runtime.
A plug-in can be visual or a unit of logic only, for example:
<Plugin id="statistics" width="0%" height="0%" includeInLayout="false"/>
This plugin is a logic plugin (no visual parts in the UI). Its attributes are width and height 0% and since includeInLayout=false, it will be hidden. The Plugin id=statistics, that means that in order to relate to the plugin instance at runtime, this will be the id of it.
Refer to the KDP 3 uiConf docs to learn more

Link your plugin from the Application Studio

Since uiConf is overridable from flashvars, it is possible to define a plugin from flashvars as well.
Use the Additional Parameters and Plugins section on the player creation window within [url=http://www.kaltura.com/index.php/kmc/kmc2#appstudio|players_list]Application Studio[/url] to link the plugin you created (and hosted on your server) to the player created using Application Studio. Decide on a name (machine readable - no spaces and starts with a character), and replace the following {Plugin name} token with the name of your plugin.

• {Plugin name}.plugin = true - Triggers the loading of the plugin. This will be the id of the plugin if and id wont be specified -- MANDATORY
• {Plugin name}.path = path - The path from where to load the plugin, if not given the plugin will be loaded from Kaltura's plugin path
• {Plugin name}.relativeTo = id - Component id within the layout to position the plugin next to -- MANDATORY
• {Plugin name}.position = [before,after,firstChild,lastChild] - relative position next to the given component id specified in relativeTo -- MANDATORY
• {Plugin name}.pluginName = class name - in case the same plugin swf contains multiple plugins
• {Plugin name}.loadingPolicy = {[wait,ondemand]} - instruct whether to wait for the plugin to load before enabling the KDP ui.
• {Plugin name}.width = A number representing the width in pixels or a number between 0 to 100 followed by % representing the width as percentage of the parent's width.
• {Plugin name}.height = A number representing the height in pixels or a number between 0 to 100 followed by % representing the height as percentage of the parent's height.
• {Plugin name}.includeInLayout = [true, false] - Default: true. Specifies whether this component is included in the layout of the parent container. If true, the object is included in its parent container's layout. If false, the object is positioned by its parent container as per its layout rules, but it is ignored for the purpose of computing the position of the next child.
• {Plugin name}.hideInFullscreen = [true, false] - Default: true. Specifies whether this component will be included in fullscreen state or not.
• {Plugin name}.visible = [true, false] - Default: true. Specifies whether the plugin's visual parts are shown or not.
• {Plugin name}.{any additional attribute} = {value} - setting any additional attribute specific to the plugin

* Note - If you'd like your plugin to be included in the displaylist and present visual elements over the player, you will need to make sure it has a defined width and height larger than 0, and the position is defined relative to another visual component. For example, overlay ad plugins usually need to be loaded above the whole video screen, make sure it has a width and height of 100% and it is positioned as the lastChild relative to the playerHolder (the id of the container component that holds the video).
myplugin.relativeTo=PlayerHolder
myplugin.position=lastChild

KDP3 Plugin creation steps

Now that we know the user part of things, let's learn how to write the actual plugin code -

• Create a new project and name it as you wish for the plugin name to be.
• Link the new project to the kdp3Lib project and set it's output bin-debug folder to the plugins folder inside the KDP_3 project.
• Create YourClassPlugin.as & YourClassPluginCode.as files.
• KDP is based on PureMVC as it's core framework, the fastest way to learn it works - refer to the PureMVC docs.
• If you need to get attributes from the uiConf, add them to the YourClassPluginCode.as as public properties and Kdp3 will automatically populate them.
• If you need to send notifications to the kdp3 you should use the KDP façade to send it.
• If you need to listen on notifications from the kdp, you need to create a mediator and register it to the various events.

Breaking down the code

The most basic plugin will have to consist the following two classes:

• YourClassPlugin.as
• YourClassPluginCode.as

YourClassPlugin

This is the document class that will be first to instantiate by the KDP3 application upon loading of the plugin, and be used as a factory to create the plugin instances.

YourClassPluginCode

This class implements IPlugin. It establishs the the core plugin that will interact and listen to KDP notifications.

When plugins are created, the first method being called is setSkin, this function should define the skin elements used by the plugin.

Second called is initializePlugin where the kdp façade is sent to the plugin for registration.
The façade (PureMVC façade) allows us to register to and trigger notification, Retrieve proxies and mediators and relate to other KDP plugins.

Plugins with visual elements - The YourClassPluginCode is also the visual component that will be added to the KDP view, make sure you add all plugin children to this class.

To listen for a KDP notification follow these steps

• Create a Mediator class, a Mediator is a Class that wraps view components and can register to the façade notifications.
• Your Mediator class should extend the base Mediator class: org.puremvc.as3.patterns.mediator.Mediator
• In your mediator class you should override listNotificationInterests and handleNotification. For example:
  
  override public function listNotificationInterests():Array
  {
          return  [ "playerPlayed" ];
  }

  override public function handleNotification(note:INotification):void
  {
          switch(note.getName())
          {
                  // this means that the main container will be 100% X 100% always
                  case "playerPlayed":
                          trace("test plugin");
                  break;
          }
  }

• Note: You do not have to pass reference to the façade from the YourClassPluginCode to YourMediator; Mediators have reference to the façade by nature when created.
• Note 2: If your plugin is short with lines of code, it is also ok to implement both interfaces (IPlugin and IPluginFactory) in the same class that will be both your plugin factory and instance (The factory will return this).

To call a KDP notification follow these steps

• Create a Mediator class, a Mediator is a Class that wraps view components and can register to the façade notifications.
• Your Mediator class should extend the base Mediator class: org.puremvc.as3.patterns.mediator.Mediator. Mediators can call KDP notifications to perform various actions like play and pause the playback, enable or disable the UI, go into FullScreen mode, etc.
• To call a notification in a Mediator call the inherited sendNotification command.
• The sendNotification: sendNotification(commandToCall:String, parametersOfTheCommand:Object)
• The following sample function shows how to call the "doPlay" notification, making the playback sequence to start:
  
  public function playMedia () : void
  {
          sendNotification("doPlay");
  }
• The following sample function shows how to call the "doPause" notification, making the playback sequence to pause:
  
  public function playPause () : void
  {
          sendNotification("doPause");
  }

Common use-cases implementations

This section provide some of the more common functions used in plugins.

Seek (jump) to time in the playing video

Often a plugins need to jump to specific locations in the playing video. A common use-case is a chapters plugin that shows a list of sections within the playing video. The following function will seek the player to a given second (float). Call this function from within your Mediator class.

Change the playing media entry

This function is used to change the playing media entry. Following a call to this function, the player will reach out to the Kaltura API asking for the new given media entry and replace the media currently playing. Call this function from within your Mediator class.

Enable or disable the player controls

The following function shows how to enable or disable the player controls. This practice is a common requirement during ads playback. Call this function from within your Mediator class.

Replacing the Kaltura Session

When implementing entitlement use cases such as pay per view or single-sign-on authentication that uses the "Free Preview" option under Access Control, a player plugin will need to communicate with 3rd party server to retrieve a new Kaltura Session after a successful authentication occurred.
Replacing the Kaltura Session used by the player is simply done by retrieving the ServicesProxy[/as]3 from the player facade, accessing the [as3]kalturaClient object (which is responsible for all Kaltura API communication) and changing the value of it ks variable. Call this function from within your Mediator class.

To learn more about the Kaltura ActionScript3 client library refer to the section below "Utilizing the Kaltura ActionScript3 Client Library".
To learn more about data proxies, refer to the section below "Playerdata proxies and their usage".

Utilizing the Kaltura ActionScript3 Client Library

KDP3 holds reference to the Kaltura client. To create and execute Kaltura API calls follow the following steps:

Get a reference to Kaltura Client

var kalturaClient : Object = facade.retrieveProxy("servicesProxy")["kalturaClient"];
Follow the Kaltura Flex Client Library guidelines.

Accessing the Video Player Object

Based on PureMVC, objects in KDP are usually accessible via their Mediators.
To access the main video player object, follow the following:

Playerdata proxies and their usage

KDP Proxies are essentially PureMVC Proxy classes used to keep application data.
In PureMVC, Proxy classes are used to manage parts of the application's data model.
A Proxy might simply manage a reference to a local data object, in which case interacting with it might involve setting and getting of its data in synchronous fashion.

Important note -
KDP Flash Plugins and KDP Javascript API access proxies in a different manner:
Inside Flash, KDP access the proxy data (the VO, "Value Object") as ProxyName.vo.fieldName. In Javascript, KDP will expose the VO fields directly in the proxy object, like so: ProxyName.fieldName. Examples:
In Flash Plugin: mediaProxy.vo.entry.name
In JS Code: mediaProxy.entry.name
In Flash Plugin: sequenceProxy.vo.isInSequence
In JS Code: sequenceProxy.isInSequence

Known Core KDP Proxies

• The "mediaProxy" – Holds information related to the media and Kaltura entry loaded.
  For example:
  mediaProxy.entry – The entry object currently playing in the KDP.
  mediaProxy.entryMetadata – The custom metadata related to the entry currently playing in the KDP (latest profile or the profile as defined in metadataProfileId flashvar).
• The "sequenceProxy" – Holds information related to the pre/post roll sequences.
  For example:
  sequenceProxy.isInSequence – Indicates whether KDP is currently playing an ad.
• The "configProxy" – Used to retrieve the flashvars.
  For Example:
  configProxy.flashvars – The flashvars used by the KDP
• The "servicesProxy" – Used to retrieve the Kaltura Client object (accessible from v3.5.7.6 and onwards) and current API session details.
  servicesProxy.kalturaClient - The KalturaClient object. For example: servicesProxy.kalturaClient.ks will retrieve the KS being used.

To see how to access proxies in KDP Flash Plugins, refer to the following example plugin:
http://www.kaltura.org/kalorg/kdp/trunk/plugins/KDPProxyDump

The KDP Proxy Dump plugin below prints all the available fields in the above core KDP proxies:

Explore KDP 3 plugins

Google Analytics

Download the KDP 3 Google Analytics plugin.
The Google Analytics plugin utilizes the gaforflash tracking library to aggregate and send statistical data to a google analytics account passed on uiConf or via flashvars.
Import the project to Flash Builder 4 and follow the inline documentation on the project two class.

The classes in the project

• googleAnalytics.as - The plugin main class, implementing IPlugin and IPluginFactory. Instantiating the mediator.
• GAStatisticsMediator.as - The mediator class, responsible for registering to the various KDP notifications and sending the events through the GATracker instance.

The use of the Google Analytics plugin with your player

Enter the KMC and click on the Studio tab. In the Studio, edit the player of your choice. Enter the Features tab. Under Additional parameters and plugins, copy and paste the following variables:

Modify the googleAnalytics.urchinCode parameter to your Google Analytics tracking id (in the form of UA-#######-#).
Change the googleAnalytics.debugMode parameter to true in order to get visual debugging information window over the player.
See more details at the Kaltura Exchange Plugin page.