Kaltura Simple Uploader (KSU) - Website Integration Guide

Sun, 08/09/2009 - 00:26 — elad.kaltura

This integration guide assumes the use of Kaltura components at the following versions:

  • Kaltura KSU widget: 1.2.4.
  • Kaltura Partner Service: 3.0 (aka api_v3)

Please be aware that if you are receiving uploadStatus="notUploaded" and the following error in API: "Unknown kshow [-1]", you are using an older version of KSU. If you are using Kaltura.com, please use the following ui_conf_id: 4211621.

Usage

Kaltura Simple Uploader (KSU) is a standalone transparent widget. It enables content administrators and/or end-users to upload media files by using a simple desktop browser selection.
Read a more detailed overview of the KSU widget.

Integration Steps

Integration of the KSU widget in your web-site requires the following steps to be followed. Steps 1 and Step 2 may be skipped if you have already integrated your web application with another Kaltura widget.
Please make sure you review these sections as well as the related FAQ before starting your integration project. Spending a moment to read this now may save you hours during your integration project.

Edit your web application scripts to integrate with the KSU widget

The KSU widget supports a variety of media upload workflows. The integration of this widget would be derived from the site-specific upload workflow you wish to implement.
Kaltura generic upload workflow consists of the following steps:

  • End-user selects media file/s to be uploaded.
  • Media file is uploaded to Kaltura system.
  • End-user sets metadata (tags, title etc.) to the uploaded media file/s, (Optional)
  • An entry is created for the uploaded media file on the Kaltura server.

The KSU widget exposes interfaces, so each workflow step could be executed separately from within JavaScript methods. It is also possible to combine steps 2 and 4 together if your workflow does not require any end-user interaction for metadata settings.
Integrating the KSU widget into your web site requires that you put the following additions into your web page:

  • Include of External Scripts and supporting styles
  • JavaScript handler methods to react to upload events
  • JavaScript callback methods to activate Kaltura services via the KSU widget
  • Construction of Kaltura objects for session initiation and population of variables to be passed to the embedded flash object
  • Location setting for the transparent KSU widget and embedding of flash object
  • Interactive form fields for dynamic user input (Optional)

Important Security Note

Due to security restrictions in Flash Player v10, any browse operation must be triggered as a result of user-interaction, therefore, user must click the swf itself in order to show the file dialogue box.
To overcome this security restriction, it's advised not to use the browse() API function, but rather place the swf above the real GUI that the user interacts with, so that the actual "click" event is triggered from the KUploader flash.

Full Example Script

The following example of PHP/JavaScript script demonstrates the integration of the KSU widget into a PHP based web application.
To run this script, please make sure you set your partner identifiers at the KALTURA_PARTNER_ID and KALTURA_PARTNER_SERVICE_WEB_SECRET constants.
Look for detailed information on this example in the following sections:

Note – Console logs calls within this example script may assist in understanding script flow. It is applicable when using Firebug extension for Mozilla Firefox browser.

Download KSU Integration script.

Download KSU Integration script with JS switch media example

Inclusion of external scripts and supporting styles

<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>

<!---set style to enable widget overlap -->
<style>
        body { margin: 0px; overflow:hidden }
        #flashContainer{ position:relative; }
                #flashContainer span{ color:#333; font-size:16px; }
                object, embed{ position:absolute; top:0; left:0; z-index:999;}
</style>

In the example lines above, external scripts, required for the KSU widget implementation, are included.
The KalturaClient.php scripts are 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 script, being used for embedding the KSU widget as a flash object.
Both scripts should be available from within the web application after proper preparation for integration.

A special style is defined within the example to enable the overlapping of the transparent KSU widget on top of the relevant GUI element to allow flash widget activation. Look for more information on this feature at the section dealing with Setting location of the transparent KSU widget and embed flash object.

Implement JavaScript handler methods to react to upload events

<script language="JavaScript" type="text/javascript">
var flashObj;
var delegate = {};

//KSU handlers
delegate.readyHandler = function()
{
        flashObj = document.getElementById("uploader");
}

delegate.selectHandler = function()
{
        console.log("selectHandler()");
        console.log(flashObj.getTotalSize());
}

delegate.singleUploadCompleteHandler = function(args)
{
        console.log("singleUploadCompleteHandler", args[0].title);
}

delegate.allUploadsCompleteHandler = function()
{
        console.log("allUploadsCompleteHandler");
}

delegate.entriesAddedHandler = function(entries)
{
        console.log(entries[0].entryId)
}

delegate.progressHandler = function(args)
{
        console.log(args[2].title + ": " + args[0] + " / " + args[1]);
}

delegate.uiConfErrorHandler = function()
{
        console.log("ui conf loading error");
}

In the example lines above a flashObj variable and a delegate array of JavaScript handler methods are being declared.
The flashObj variable points to the KSU flash application, thus enables external control on widget’s functionality.
The delegate array holds JavaScript handler methods allowing web applications to implement their workflow upon notification of media upload events arriving from the Kaltura servers. The following list describes the handler events and their applicative meaning.

Callback ID Description Parameters
delegate.readyHandler The readyHandler method is activated upon server notification of successful load of the KSU widget. This event signals to the web application that the flash object is ready to interact with the JavaScript handler methods. The implementation of this method must include an initiation of the flashObj object. N/A
delegate.selectHandler The selectHandler method is activated upon server notification of successful selection of media file/s to be uploaded. Web-applications may want to use this handler to inform end-users of the event. N/A
delegate.singleUploadCompleteHandler The singleUploadCompleteHandler method is activated upon server notification of successful upload of one selected media file. It passes a single item array of entry objects, holding information on the uploaded file. Arg[0].title may be in use by web-applications whishing to use this handler to inform end-users on the event. Arg = Array of single entry object
delegate.allUploadsCompleteHandler The allUploadsCompleteHandler method is activated upon server notification of successful upload of all media files selected within one session. Web-application may want to use this handler to inform end-users on the event. N/A
delegate.entriesAddedHandler The entriesAddedHandler method is activated upon server notification of successful entry creation for all media files selected in one session. It passes an array of Kaltura entry objects as an argument. entries[i].title may be in use by web-applications whishing to use this handler to inform end-users of the event.
    entries = Array of entry objects

  • entries[i].title
  • entries[i].entryID
delegate.progressHandler The progressHandler method enables web applications to implement progress bar, informing users of the progress of long uploads based on notification from Kaltura servers.
    Arg = Array

  • Arg[0] = number of bytes already loaded
  • Arg[1] = total number of bytes to upload
  • Arg[2] = Kaltura entry object containing information on the uploaded media file.
  • Arg[2].title holds info on media name
delegate.uiConfErrorHandler This uiConfErrorHandler method is activated upon server notification of failure in uploading the KSU widget configuration XML N/A

Implement callback methods to activate Kaltura services via the KSU widget

//KUplaoder callbacks  
function upload()
{
        flashObj.upload();
}

function setTags(tags, startIndex, endIndex)
{
        flashObj.setTags(tags, startIndex, endIndex);
}

function addTags(tags, startIndex, endIndex)
{
        flashObj.addTags(tags, startIndex, endIndex);
}
function setTitle(title, startIndex, endIndex)
{
        flashObj.setTitle(title, startIndex, endIndex);
}

function getFiles()
{
        var files = flashObj.getFiles();
        console.log(files[0].title);
}

function addEntries()
{
        flashObj.addEntries();
}

function stopUploads()
{
        flashObj.stopUploads();
}

function setMaxUploads(value)
{
        flashObj.setMaxUploads(value);
}

function setPartnerData(value)
{
        flashObj.setPartnerData(value);
}

function setMediaType()
{
        var mediaType = mediaTypeInput.value;
        console.log(mediaType);
        flashObj.setMediaType(mediaType);
}

function addTagsFromForm()
{
        var tags = document.getElementById("tagsInput").value.split(",");
        var startIndex = parseInt(tagsStartIndex.value);
        var endIndex = parseInt(tagsEndIndex.value);
        addTags(tags, startIndex, endIndex);
}

function setTitleFromForm()
{
        var startIndex = parseInt(titleStartIndex.value);
        var endIndex = parseInt(titleEndIndex.value);
        setTitle(titleInput.value, startIndex, endIndex);
}

function removeFilesFromForm()
{
        var startIndex = parseInt(removeStartIndex.value);
        var endIndex = parseInt(removeEndIndex.value);
        flashObj.removeFiles(startIndex, endIndex)
        console.log(flashObj.getTotalSize());
}

function setGroupId(value)
{
        flashObj.setGroupId(value);
}

function setPermissions(value)
{
        flashObj.setPermissions(value);
}

function setSiteUrl(value)
{
        flashObj.setSiteUrl(value);
}

function setScreenName(value)
{
        flashObj.setScreenName(value);
}

//set parameters to be taken from user input field
var tagsInput;
var tagsStartIndex;
var tagsEndIndex;

var titleInput;
var titleStartIndex;
var titleEndIndex;

var removeStartIndex;
var removeEndIndex;
var maxUploadsInput;

var partnerDataInput;
var mediaTypeInput
var groupId;
var permissions;
var screenName;
var siteUrl;

function onLoadHandler()
{
        tagsInput = document.getElementById("tagsInput");
        tagsStartIndex = document.getElementById("tagsStartIndex");
        tagsEndIndex = document.getElementById("tagsEndIndex");

        titleInput = document.getElementById("titleInput");
        titleStartIndex = document.getElementById("titleStartIndex");
        titleEndIndex = document.getElementById("titleEndIndex");

        removeStartIndex = document.getElementById("removeStartIndex");;
        removeEndIndex = document.getElementById("removeEndIndex");

        maxUploadsInput = document.getElementById("maxUploadsInput");
        partnerDataInput = document.getElementById("partnerDataInput");

        groupId = document.getElementById("groupId");
        permissions = document.getElementById("permissions");
        screenName = document.getElementById("screenName");
        siteUrl = document.getElementById("siteUrl");
        mediaTypeInput = document.getElementById("mediaTypeInput");
}
</script>

In the example lines above, JavaScript callback methods were implemented to activate Kaltura services upon application workflow or end-user actions. Kaltura services are being activated by calling public methods of the KSU widget.
In order to allow maximum workflow flexibility each method implements a specific functionality. These functionalities may be used/combined/altered according to workflow requirements.

Method Signature Description JS enabled
upload():void The upload method activates Kaltura upload services for uploading of all media files selected at the desktop browser within the current session. If the upload process was previously stopped, it will start from the file whose upload was cancelled. Yes
setTags(tags:Array, startIndex:int, endIndex:int):void The setTags method overrides existing tags for the selected media file/s. the startIndex and endIndex parameters indicate the specific media files this tag should apply for. StartIndex should be set to 0 for the first selected file.
For example: user selects 5 media files: f1,f2,f3,f4,f5 then tag1 is being set at startIndex=2 and endIndex=4. tag1 will override all existing tags for f3,f4,f5.		 Yes
addTags(tags:Array, startIndex:int, endIndex:int):void The addTags method adds tags for the selected media file/s. the startIndex and endIndex parameters indicate the specific media files this tag should be added for. StartIndex should be set to 0 for the first selected file.
For example: user selects 5 media files: f1,f2,f3,f4,f5, then tag1 is being set at startIndex=2 and endIndex=4. tag1 will be added to the existing tags of f3,f4,f5.
setTitle(title:String, startIndex:int, endIndex:int):void The SetTitle method sets titles for the selected media file/s. the startIndex and endIndex parameters indicate the specific media files this title should be set for. StartIndex should be set to 0 for the first selected file.
For example: user selects 5 media files: f1,f2,f3,f4,f5, then title1 is being set at startIndex=2 and endIndex=4. title1 will be set to f3,f4,f5.		 Yes
getFiles():Array The getFiles method retrieves an array of Kaltura entry objects for the selected media files. Each entry object contains metadata and other information including entryId, if already available. Yes
addEntries():void The addEntries method activates Kaltura entry creation services. This is the final step in uploading media files, an entry is created for each uploaded file and an entryId is generated as a unique identifier for the uploaded media within the Kaltura system Yes
stopUploads():void The stopUploads method activates Kaltura services to abort the current upload process. Yes
setMaxUploads(value:uint):void The setMaxUploads method overrides the current limit of maximum number of files to be selected by end-users at the desktop browser at one session. This value could also be pre-populated within the flashVars array Yes
setPartnerData(value:String):void The setPartnerData method sets an additional site-specific metadata field to the uploaded media. This value coVuld also be pre-populated within the flashVars array Yes
setMediaType(mediaType:String):void The setMediaType Sets the media type to show in the file dialogue. The media types are defined in the UI conf file. The common types to be set as arguments for this method are: “video”, “audio”, “image”.
setGroupId(value:String):void The setGroupId method sets the group ID. This value could also be pre-populated within the flashVars array. Yes
setPermissions(value:String):void The setPermissions method sets the permission level. This value could also be pre-populated within the flashVars array. Yes
setSiteUrl(value:String):void The setSiteUrl method sets site URL as a metadata parameter. Yes
setScreenName(value:String):void The setScreenName method sets the screen name of the uploading user, when applicable. Yes
getError():String The getError method returns the current error if any exists, otherwise it returns null. Possible values: “fileSizeExceeds” ,”totalSizeExceeds” ,”numFilesExceeds” ,”uploadError”. Yes

Construct Kaltura objects for session initiation and populate variables to be passed to the embedded flash object

<body onload=onLoadHandler()>
<?php
//define constants
define("KALTURA_PARTNER_ID", Your Partner ID);
define("KALTURA_PARTNER_WEB_SERVICE_SECRET", "Your Partner Web Service Secret");

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

//Construction of Kaltura objects for session initiation

$config           = new KalturaConfiguration(KALTURA_PARTNER_ID);
$client           = new KalturaClient($config);
$ks               = $client->session->start(KALTURA_PARTNER_WEB_SERVICE_SECRET, $partnerUserID, KalturaSessionType::USER);

$flashVars = array();

$flashVars["uid"]   = $partnerUserID;
$flashVars["partnerId"]                         = KALTURA_PARTNER_ID;
$flashVars["subPId"]                    = KALTURA_PARTNER_ID*100;
$flashVars["ks"]   = $ks;
$flashVars["conversionProfile"]   = 5;
$flashVars["maxFileSize"]   = 10;
$flashVars["maxTotalSize"]   = 50;
$flashVars["uiConfId"]   = 11500;
$flashVars["jsDelegate"]   = "delegate";
$flashVars["entryId"] = -1;
?>

In the example lines above 2 constants and one variable are defined, later to be used within implementation. The PHP code constructs the relevant Kaltura objects, being used for session initiation. The objects are being constructed as defined and implemented in the relevant Kaltura API Client Library.

Parameter Type Default Description
KALTURA_PARTNER_ID Numeric N/A Here you should put your partner ID. Please refer to the How to Obtain Partner Identifiers page for reference.
KALTURA_PARTNER_WEB_SERVICE_SECRET String N/A Here you should put your Web Service Secret. Please refer to the How to Obtain Partner Identifiers page for reference. This Secret string is being 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” Here you are able to populate your internal system end-user identifier. This variable will be used to relate the uploaded content to its uploading user. It may be used by Kaltura partners for user management and statistics tracking.

In the example lines above, the PHP/JavaScript code is preparing the flashVars array, later to be passed to the embedded object.
Below is a description of some applicative parameters being transferred to the KSU flash object via the flashVars array.
Some of these variables are being set at an internal configuration xml as well. Passing these parameters at the flashVars array will override this configuration:

Parameter Description Data Type/Required Defined in Widget ConfUI xml Default
$flashVars["uid "] This is the end-user internal identifier String/Required No N/A
$flashVars["partnerId"] This is the Partner ID Int/Required No N/A
$flashVars["subPId"] This is the Sub Partner ID, its value should equal to Partner_ID*100 Int/Required No N/A
$flashVars["entryId"] Internal Parameter - Mandatory Int/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["conversionProfile"] This parameter sets the media conversion method to be applied on the uploaded media file Int/Optional Yes 5
$flashVars["maxFileSize"] This parameter sets a restriction on the maximum file size to be applied on the uploaded media file Int/Optional Yes N/A
$flashVars["maxTotalSize"] This parameter sets a restriction on the total maximum file sizes to be applied within one upload session Int/Optional Yes
$flashVars["uiConfId"] This is the configuration xml id of the KSU widget Int/Required No 11500
$flashVars["jsDelegate"] This is the exact name of the array of JS handler methods String/Required No “delegate”

Set the location of the transparent KSU widget and embed flash object

<div id="flashContainer">
        <form>
                <input type="button" value="Step 1 - Browse & Select">
        </form>
        <div id="uploader">
        </div>
        <script language="JavaScript" type="text/javascript">
                var params = {
                        allowScriptAccess: "always",
                        allowNetworking: "all",
                        wmode: "transparent"

                };
                var attributes  = {
                        id: "uploader",
                        name: "KUpload"
                };
                // set flashVar object
                var flashVars = <?php echo json_encode($flashVars); ?>;
                 <!--embed flash object-->
                swfobject.embedSWF("http://www.kaltura.com/kupload/ui_conf_id/4211621", "uploader", "200", "30", "9.0.0", "expressInstall.swf", flashVars, params,attributes);
        </script>
</div>

In the example lines above, a flashContainer div is set to contain the transparent flash object of the KSU widget.

The KSU widget has to be located on top of the actual GUI element your end-users interact with when they want to open a desktop browser. This is needed in order to overcome flash security restriction, allowing browse operations to be triggered as a result of user-interaction.

The image below demonstrates the transparent KSU widget (marked with the dotted line) located on top of a functionless “Select & Browse” button (set within an html span tag at the example). This way the desktop browser is triggered from the KSU widget itself upon clicking the button.

Kaltura Simple Uploader Screen-shot

The uploader div is set as a SWFObject’s alternative content container; please refer to Google hosted SWFObject documentation for additional information on why this is needed. Make sure that the ID of this div element is the same as the ID of the embedded flash object.

The params and attributes variables are set. Make sure their elements are set as in the above example to allow object transparency and proper communication with the KSU widget.

Finally, a JavaScript call to swfobject.embedSWF function is made; this is the actual embedding of the KSU widget. The applicative parameters being passed as arguments in this example are:

Parameter Type/Required Default/Suggested Description
Flash File URL String/Required http://www.kaltura.com/kupload/ui_conf_id/11500 The file path and name of the KSU flash file.
ID String/Required “uploader” ID of embedded object. Make sure this string is the same as the name of the alternative content div for the SWFObject to operate properly.
width String/Required The width of the transparent KSU Flash Object
height String/Required “30” The height of the transparent KSU Flash Object
Version String/Required "9.0.0" Specifies the Flash player version the KSU 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 at flashvars array of name:value pairs
Params String/Required
                var params = {

        allowScriptAccess: "always",

        allowNetworking: "all",

        wmode: "transparant"

};

 Flash object generic parameters at an array of with name:value pairs. Make sure vmode is set to transparent
Attributes String/Required
                var attributes = {

        name: "KUpload",

        id: "uploader"

};

 Object attributes at an array of name:value pairs. The name attribute must be “KUpload”. The id attribute can be set to the id you assign to your object and to your SWFObject alternative content div/

Please look for more information on the swfobject.embedSWF method in the Google hosted SWFObject documentation page.

Implement input fields for dynamic user input (Optional)

<div id="userInput">
        < input type="button" value="Step 2 - Upload"           onclick="upload()">
        < input type="button" value="Step 3 - Add entries"      onclick="addEntries()">
        < input type="button" value="Cancel"            onclick="stopUploads()">

        < input type="text" id="mediaTypeInput" />
        < input type="button" value="Set media type" onclick="setMediaType()">

        < input type="button" value="Get Files Objects " onclick="getFiles()">

        < input type="text" value="enter tags here" id="tagsInput" />
        < input type="text" value="0" id="tagsStartIndex" />
        < input type="text" value="0" id="tagsEndIndex" />
        < input type="button" value="Add tags" onclick="addTagsFromForm()">
        < input type="button" value="Set tags" onclick="setTagsFromForm()">

        < input type="text" value="enter title here" id="titleInput" />
        < input type="text" value="0" id="titleStartIndex" />
        < input type="text" value="0" id="titleEndIndex" />
        < input type="button" value="Set title" onclick="setTitleFromForm()">

        < input type="text" value="0" id="removeStartIndex" />
        < input type="text" value="0" id="removeEndIndex" />
        < input type="button" value="Remove Files" onclick="removeFilesFromForm()">

        < input type="text" value="0" id="maxUploadsInput" />
        < input type="button" value="Set max uploads" onclick="setMaxUploads(parseInt(maxUploadsInput.value))">

        < input type="text" value="partner data goes here" id="partnerDataInput" />
        < input type="button" value="Set partner data" onclick="setPartnerData(partnerDataInput.value)">
        < input id="groupId" />
        < input type="button" value="set group id " onClick="setGroupId(groupId.value)">
        < input id="permissions" />
        < input type="button" value="set permissions" onClick="setPermissions(permissions.value)">
        < input id="screenName" />
        < input type="button" value="Set screen name" onClick="setScreenName(screenName.value)">
        < input id="siteUrl" />
        < input type="button" value="set site url" onClick="setSiteUrl(siteUrl.value)">
</div>

In the example lines above, a few interactive form fields are set to enable Kaltura partner’s integrators to test and activate Kaltura services using the KSU widget. These forms were set for example purposes only. Please use the relevant methods according to your web application workflow.

Errors – Flash player Exceptions

  • Limitations error – "Cannot upload, limitations exceeded. Please check for errors" - thrown if the upload() function is invoked while an error *exists.
  • Upload error - "Cannot add entries, some uploads failed. Either re-upload or remove the files" - thrown if the addEntries() function is invoked while an error *exists.

The error can be polled by calling getError();

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

AttachmentSize
ksu-integration-script.zip16.64 KB
ksu-integration-script.zip16.69 KB
‹ Go to "Kaltura Simple Uploader (KSU) - uiConf and filetype filters"Go to Parent Page
Back to top

Comments

nothing is happening

Fri, 11/19/2010 - 00:26 — iotmadmin

I followed the instructions to set up a simple uploader, everything seems to check out ok, however, after selecting a file, nothing is happening? no files are transferred. What can be done to test it further?