KDP APIs - about JavaScript integration

• This guide refers only to KDP version 2.0.2 and above.
• For first time integration, please follow this Playback Guide first.

Introduction

The KDP provides API to its wrapper (JavaScript in most implementations) that enables calling to public KDP methods and registering to events triggered by the KDP that control to KDP behavior and actions. (implemented using the ExternalInterface)

Using the API it is possible to control various application and playback behaviors such as; play, pause, seek (jump to time), open and close windows and more.

Click here for a KDP API implementation example.

Perquisites

• KDP basic usage.
• This article make use of JQuery.
• Suggested: Chromeless KDP.

Registering to Events

To react to the various events, an event listener must be defined and point to a JavaScript function that will handle it.
To define an event listener use the following syntax –
myKdp.addJsListener("event_name","handler_function");

• event_name - is the name of the event to listen to (see table for list of available events).
• Handler_function – is the name of the JavaScript function defined on page that will be called when the event will fire.

It is possible to add event listeners to the KDP only after all of the following conditions are met:

• The KDP has finished initializing and is ready to be used (onKdpReady/onKdpEmpty).
• The externalInterfaceDisabled flashVar is set to 0 (or don't pass this flashVar at all).
• The allowScriptAccess parameter on the Object tag is set to always.
• Both the name and id attributes on the Object tag should be defined with the same value (To be able to access the KDP object in JavaScript).

KDP initialization, identifying the Ready state

There are 2 ways that KDP indicate that initialization has finished and it is ready to be used (Ready State).

• onKdpReady - The KDP was fully initialized and loaded with a valid entry/url and the media was successfully loaded.
• onKdpEmpty - The KDP was fully initialized, but did not load any media (like in a gallery mode where the player is loaded with no content, and wait for user interaction to get the media to load).

Because the KDP isn't ready yet, the ExternalInetrface isn't available so to listen to these events,
pass in the flashVar parameter of the KDP Object tag the name of the JavaScript functions that will be called when this event is dispatched,
like in the following examples;
Using HTML:

Using SWFObject:

In the above examples, both of the events (emptyF and readyF) will cause the same JavaScript function "onKdpReady" to be triggered.
In the JavaScript the onKdpReady will be defined as follow, providing the KDP element id in the playerId parameter:

Remember to specify the name and id attributes to the same value on the KDP Object tag for the playerId to return the right element id:
HTML:

JavaScript:

In this stage, the KDP is ready (and ExternalInterface is available).
Now it is possible to register events to it and dispatch events to trigger various commands such as play, pause, seek...

KDP Events And Commands

KDP events are divided into two types –

• Event that provide additional information about the performed action (like the playhead time).
• Simple events with no additional data.

JavaScript functions that are registered to events that carry additional data, require that the data parameter will be defined in the handler function signature, for example, to determine the playhead time position during playback, the playerUpdatePlayhead event must be registered and it’s handler function should define a data object containing the new time position value.
Using Jquery to access the kdp object via JavaScript:

To know when the KDP volume has changed:

In this case the "volumeChange" event contains the KDP volume value.

Remove an Event Listener (Stop getting event notifications)

To remove the listener of a specific event, use opposite API "removeJsListener":

• event_name - is the name of the event to listen to (see table for list of available events).

Dispatching KDP Events - Calling KDP Methods to perform actions

To command the KDP to perform certain actions, a command event must be dispatched.
To dispatch a command event, use the dispatchKdpEvent("event_name", values);

• event_name - is the name of the event to listen to (see table for list of available events).
• values - (optional) A value to be passed as the action parameter (e.g. the volume level value (0-1) when setting a new volume level).

Examples:

Special public functions

In addition to the events, KDP also provide a few specific public functions to ease the integration and use direct method calls instead of dispatching events:

• insertMedia - command the player to play a new media (overrides last entry in case it was playing something).
  myKdp.insertMedia(kshow_id:String = "-1", entry_id:String = "-1", auto_play:String = "false", entry_version:String = "-1");
  • kshow_id - Deprecated (used to load a specific kshowId).
  • entry_id - the id of the kaltura entry to load, or a URL to media.
  • auto_play - Boolean, if true, media will play immediately. false will make the player wait for user interaction.
  • entry_version - specific version id of the entry to load.
• getMediaSeekTime - get the position of the video playhead. A way to ask the KDP for its playhead time value.
  
  alert(myKdp.getMediaSeekTime());
• seekMedia - jump to a specific time.
  
  //seek to the 10th second.
  myKdp.seekMedia(10);
• stopMedia - stop playback and jump back to start. myKdp.stopMedia();
• pauseMedia - pause playback. myKdp.pauseMedia();
• playMedia - start playback. myKdp.playMedia();
• evaluate - Evaluate variables from the KDP model [more].
  
  //e.g. getting the playing entry id:
  alert ("The currently playing entry id is " + kdp.evaluate("{entry.id}"));

KDP Events

The following list of events are available both as public events dispatched by the kdp (to be used when embedded inside another Flash application), and as ExternalInetrface events available for the dispatchKdpEvent and addJsListener methods.

Notifiers (events that notify of a performed action or change)

Commands (events that will cause an action to be performed)