Kaltura Contributor Wizard (KCW) - Website Integration

Printer-friendly version

Prerequisites

  • Kaltura KCW widget: 2.1.6
  • Kaltura Partner Service: 3.0 (api_v3)

Usage

The Kaltura Contributor Wizard (KCW) is a standalone GUI widget enabling content administrators and/or web sites’ end-users to conveniently upload and use video, image and audio media files.  See Overview of the KCW widget.

Integration Steps

To get started please read Kaltura API usage guidelines.

Edit your Web Page to Integrate with the Kaltura Contributor Wizard widget

Integrating the KCW Widget into your website requires that you add the following into your web page:

Full Example Script

The following example of PHP/JavaScript script demonstrates the integration of the KCW Widget into a PHP based web application. 
To run this script,be certain that you set your partner identifiers for the KALTURA_PARTNER_ID and KALTURA_PARTNER_SERVICE_SECRET constants. 
Look for detailed information on this example in the following sections:

<html>
<head>
<!--include external scripts-->
<?php require_once("KalturaClient.php"); ?>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
</head>
 

<body>
<?php
//define constants
define("KALTURA_PARTNER_ID", Your Kaltura Partner ID);
define("KALTURA_PARTNER_SERVICE_SECRET", " Your Kaltura Service Secret");

//define session variables
$partnerUserID          = 'ANONYMOUS';

//construct Kaltura objects for session initiation
$config           = new KalturaConfiguration(KALTURA_PARTNER_ID);
$client           = new KalturaClient($config);
$ks               = $client->session->start(KALTURA_PARTNER_SERVICE_SECRET, $partnerUserID, KalturaSessionType::USER);

//Prepare variables to be passed to embedded flash object.
$flashVars = array();
$flashVars["uid"]               = $partnerUserID;
$flashVars["partnerId"]         = KALTURA_PARTNER_ID;
$flashVars["ks"]                  = $ks;
$flashVars["afterAddEntry"]     = "onContributionWizardAfterAddEntry";
$flashVars["close"]       = "onContributionWizardClose";
$flashVars["showCloseButton"]   = false; 
$flashVars["Permissions"]       = 1;

?>
<div id="kcw"></div>
<script type="text/javascript">
var params = {
        allowScriptAccess: "always",
        allowNetworking: "all",
        wmode: "opaque"
};
// php to js
var flashVars = <?php echo json_encode($flashVars); ?>;

<!--embed flash object-->
swfobject.embedSWF("http://www.kaltura.com/kcw/ui_conf_id/1000741 ", "kcw", "680", "360", "9.0.0", "expressInstall.swf", flashVars, params);
</script>

<!--implement callback scripts-->
<script type="text/javascript">
function onContributionWizardAfterAddEntry(entries) {
        alert(entries.length + " media file/s was/were succsesfully uploaded");
        for(var i = 0; i < entries.length; i++) {
                alert("entries["+i+"]:EntryID = " + entries[i].entryId);
        }
}
</script>
<script type="text/javascript">
function onContributionWizardClose() {
        alert("Thank you for using Kaltura ontribution Wizard");
}
</script>

</body>
</html>

Inclusion of External Scripts

The KalturaClient.php script is part of the PHP Kaltura API Client Library being included to enable the use of Kaltura objects. The swfobject.js script is the Google hosted SWFObject, being used for embedding the KCW widget as a flash object.

<head>
<!--include external scripts-->
<?php require_once("KalturaClient.php"); ?>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
</head>

Define Constants and Variables

In the following example, the PHP code defines 2 constants and one variable, later to be used within implementation.

//define constants
define("KALTURA_PARTNER_ID", Your Kaltura Partner ID);
define("KALTURA_PARTNER_SERVICE_SECRET", “Your Kaltura Service Secret”); 

//define session variables
$partnerUserID          = 'ANONYMOUS';

The following lists the constants and variable parameters and their descriptions.

Parameter Data Type Default Value Description
KALTURA_PARTNER_ID Numeric N/A Enter your Partner ID. Please refer to Kaltura API usage guidelines.
KALTURA_PARTNER_SERVICE_SECRET String N/A Enter your Web Service Secret. Refer to Kaltura API usage guidelines for more information. The Secret string is used within Kaltura objects to create a secured session ID, preventing hacking and abuse attempts aiming to damage Partner/end-user’s content.
partnerUserID String "ANONYMOUS" Use to populate your internal system end-user identifier. This variableis  used to relate the uploaded content to its uploading user, and be used by Kaltura partners for user management and statistics tracking.

Construct Kaltura Objects for Session Initiation

In the following example, the PHP code constructs the relevant Kaltura objects that are used for session initiation. The objects are constructed as defined and implemented in the relevant Kaltura API Client Library.

//construct Kaltura objects for session initiation
$config           = new KalturaConfiguration(KALTURA_PARTNER_ID);
$client           = new KalturaClient($config);
$ks               = $client->session->start(KALTURA_PARTNER_SERVICE_SECRET, $partnerUserID,KalturaSessionType::USER);

 

Prepare Variables to be Passed to Embedded Flash Object

In the following example, the PHP/JavaScript code is preparing the flashVars and params variables to be passed to the embedded object.

//Prepare variables to be passed to embedded flash object.
$flashVars = array();
$flashVars["uid"]               = $partnerUserID;
$flashVars["partnerId"]         = KALTURA_PARTNER_ID;
$flashVars["ks"]                  = $ks;
$flashVars["afterAddEntry"]     = "onContributionWizardAfterAddEntry";
$flashVars["close"]             = "onContributionWizardClose";
$flashVars["showCloseButton"]   = false; 
$flashVars["Permissions"]       = 1;
?>
<div id="kcw"></div>
<script type="text/javascript">
var params = {
        allowScriptAccess: "always",
        allowNetworking: "all",
        wmode: "opaque"
};
// php to js
var flashVars = <?php echo json_encode($flashVars); ?>; 

Below is a description of some applicative parameters that are transferred to the KCW flash object via the flashVars array. Some of these variables are also set in an internal configuration xml. Passing these parameters at the flashVars array will override this configuration:

Parameter Description Data Type Required / Optional Defined in Widget Config xml Default Value
$flashVars["uid"] This is the end-user internal identifier String Required No N/A
$flashVars["partnerId"] This is the Partner ID String Required No N/A
$flashVars["ks"] This is the unique Kaltura session ID as was generated by Kaltura API Client objects String Required No N/A
$flashVars["afterAddEntry"] This is the name of the JavaScript function to be implemented as a callback for the afterAddEntry event of the KCW widget. The callback mechanism is described at the“Define and implement callback methods to be activated upon widget events” section String Required No "afterAddEntry"
$flashVars["close"] This is the name of the JavaScript function to be implemented as a callback for the close event of the KCW widget; it is being triggered upon pressing the close button of the widget (when enabled), or upon pressing the ‘finish’ button after a successful uploading. The callback mechanism is described at the“Define and implement callback methods to be activated upon widget events” section String Required No "close"
$flashVars["showCloseButton"] This variable controls the use of the KCW close button. When this variable is set to false, no close button will appear within the KCW widget. It makes sense to hide this button when the KCW widget is an integral part of your web page. When you embed the KCW widget within a lightbox layer, you may choose to show the close button, by setting this variable to true. Boolean Optional Yes True
$flashVars["Permissions"] This variable defines who will be able to see the uploaded media file.
  1. public
  2. private
  3. group
  4. friends
int Optional No 1

The flashVars array being populated at the above example should be transferred into an appropriate format, using php json_encode method, just before being transferred into the embedded object.

Embed Flash Objects

The following example shows how a JavaScript call to swfobject.embedSWF function is being made; this is the actual embedding of the KCW Widget. 

<!--embed flash object-->
swfobject.embedSWF("http://www.kaltura.com/kcw/ui_conf_id/1000199", "kcw", "680", "360", "9.0.0","expressInstall.swf", flashVars, params);
</script> 

The applicative parameters being passed as arguments at this example are:

 
Parameter Data Type Required/Optional Default Value Description
Flash File URL String Required The url should be constructed in the following template:
http://{kaltura_server_domain}/kcw/ui_conf_id/{id_of_uiconf}
If you are using the hosted edition on Kaltura.com, the following two are available as a start:
  • Dark colors widget: http://www.kaltura.com/kcw/ui_conf_id/1000740
  • Light color widget: http://www.kaltura.com/kcw/ui_conf_id/1000741
The file path and name of the KCW flash file at a specific Look & Feel.
ID String Required "kcw" Id of embedded object
width String Required You should use "680" The width of the KCW Flash Object
height String Required You should use "360" The height of the KCW Flash Object
Version String Required KCW require Flash Player 9 and above, so use: "9.0.0" Specifies the Flash player version the KCW flash object is published for
ExpressInstallSwfurl String Optional “false” Specifies the URL of your express install SWF and activates Adobe express install when needed. When set to “false” the express install will not be activated
FlashVars String Required N/A Applicative information for flashvars object constructed as such {parameter1_name:parameter1_value,parameter2_name:parameter2_value} pairs
Params String Required We recommand using the following: [javascipt]var params = {
allowScriptAccess: "always",
allowNetworking: "all",
wmode: "opaque"
};[/javascipt]
flash object generic parameters constructed as such {parameter1_name:parameter1_value,parameter2_name:parameter2_value} pairs

Please look for more information on the [javascipt]swfobject.embedSWF[/javascipt] method at Google SWFObject documentation page.

Define and Implement Callback Methods to be Activated upon Widget Events

<!--implement callback scripts-->
<script type="text/javascript">
function onContributionWizardAfterAddEntry(entries) {
        alert(entries.length + " media file/s was/were succsesfully uploaded");
        for(var i = 0; i < entries.length; i++) {
                alert("entries["+i+"]:EntryID = " + entries[i].entryId);
        }
}
</script>
<script type="text/javascript">
function onContributionWizardClose() {
        alert("Thank you for using Kaltura Contribution Wizard");
}
</script> 

Kaltura enables developers to implement event based communication between the KCW Widget and their web applications. This is achieved by using the JavaScript callback functions, implemented by developers, according to the applicative needs of their web sites. The KCW communicates with web application upon 2 events:

Callback ID Description Parameters
Configurable and determined by flashVars
afterAddEntry = callback ID
at the example:
afterAddEntry =onContributionWizardAfterAddEntry
This event is being triggered upon a completion of content (Entry) uploading. Entries = array of FileVO objects. 
Each FileVO object contains information for the uploaded media file.

at the example:
Entries[i].entryId represents the unique identifier of the uploaded media within the Kaltura system. 
It may be used to integrate the KCW widget with other widgets/applications
Entries[i].MediaType represents the media type of the uploaded media
Video=1/image=2/Audio= 5
Configurable and determined by flashVars
close = callback ID
at the example:
close = onContributionWizardClose
This event is being triggered upon a completion of content (Entry) uploading. N/A

Passing Partner Data to the KCW Widget

Kaltura partner’s site-specific workflow may require the KCW Widget to receive and store additional data per uploaded content. While Kaltura provides several generic metadata fields attached to each entry, such as title and tags, it is sometimes necessary to relate additional site-specific data to the uploaded content. Kaltura enables this metadata flexibility by supporting a dedicated partner data field. This field may contain up to 1K characters and can include an XML structure if multiple parameters are needed.

Partner’s data is being handled differently in the 2 following cases:

  • Static Partner data
    Partner data is available before the KCW Widget is embedded. This is mainly the case when partner data is constant within the same web page. For example, you allow content uploading from several locations on your website and you want to relate the uploaded content to the exact URL it was uploaded from.
    In this case an additional flashVar pair should be added when preparing the flashVar array before embedding the KCW Widget.
    Parameter Description Data Type Required Defined in Widget Config xml Default Value
    $flashVars["partnerData"] This parameter will hold any partner specific data and will store it with every uploaded content entry. It is possible to use this parameter to pass more than one data item within an XML structure. This field may contain up to 1K characters String Optional No N/A
  • Dynamic Partner data
    Partner data is not available before the KCW Widget is embedded. This is mainly the case when partner data relies on end-user interaction. For example, you want your end-users to be able to relate their uploaded content with a specific filter which you want to use for specific purpose within your website.

    In this case the KCW flash object should be updated with the additional data when it’s available using KCW’s public methodsetPartnerData

    Method signature Description JS Enabled
    setPartnerData(value:*):void Sets the partner data Yes

    In the example below, partner data could be set by end-users at the partnerData text field. Clicking the ‘set partner data’ button activates a java script function that passes this data to the KCW flash object (identified by its “kcw”id).

    <br/>
     
    
    <form>
    
     <input id="partnerData" />
    
     <input id="nextButton" type="button" value="set partner data" onClick="changePData()">
    
    </form>
    
    <script type = “text/javascript>
    
    function changePData()
    
    {
    
     var pData = document.getElementById("partnerData").value;
    
     var flashObj = document.getElementById("kcw");
    
     flashObj.setPartnerData(pData);
    
    }
    
    </script>

Implementing External Control on Flash Object Steps

When passing dynamic partner data to the KCW widget, it may raise a workflow need to change/control the internal steps of the KCW widget. This may be needed in order to set the additional partner data before media entry is created on the Kaltura system for the uploaded file.
Therefore you need to allow end-users to upload their content only after they chose a site-specific filter related to it.
It is possible to externally control KCW steps, using the following KCW public methods and JavaScript events:

Method signature Description JS Enabled
goNextStep():void Changes the kcw import state to the next one Yes
goPrevStep():void Changes the kcw import state to the previous one Yes

The following example suggests a way to override the functionality of KCW widget’s “back” and “upload/next” built-in buttons and to externally control its internal steps. Combining such an implementation along with hiding the built-in control buttons of the KCW widget (using overlapping div) can enable site-specific workflow while relating dynamic data to uploaded content.

<!--implement advanced partner data communication functionality-->
<br/>
 

<form>

 <input id="backButton" type="button" value="Back" onClick="back()">

 <input id="nextButton" type="button" value="Next" onClick="next()">

</form>

<script type="text/javascript">

function next()

{

        var flashObj = document.getElementById("kcw");

        flashObj.goNextStep();

}

function back()

{

       

        var flashObj = document.getElementById("kcw");

        flashObj.gobackStep();

}

function nextButtonChanged(label, isEnabled, visible)

{

        var nextButton = document.getElementById("nextButton");

        setButtonMode(nextButton, isEnabled, label)

}

function backButtonChanged(label, isEnabled, visible)

{

        var backButton = document.getElementById("backButton");

        setButtonMode(backButton, isEnabled, label)

}

function setButtonMode(buttonObj, isEnabled, label)

{

        buttonObj.disabled = !isEnabled;

        buttonObj.value = label;

}

function kcwPendingChangeHandler(pending)

{

    document.getElementById("nextButton").disabled = pending ?

        true :

        false;

    document.getElementById("backButton").disabled = pending ?

            true :

            false;

}

</script>

For further problem solving and details please refer to the Frequently Asked Questions on the KCW Integration guide.