Enhance Your Video Experience with Our Collection of APIs

This article takes you to the first steps in making your first video integration with the VIXY API.

Full documentation

This article takes you to the first steps in making your first video integration with the VIXY API.  There is a full documentation available at the following location:

https://platform.vixyvideo.com/api_v3/testmeDoc/


There you will also find is also a test console where you can test the full API in an interactive interface and get code samples for generating them in various programming languages when using our client libraries - which are also available for download there.


Keeping secrets secret

When logged in to the Online Video platform there are two secrets available under system > integration settings, the admin and user secret. The difference between the two is that the user secret has less privileges than the admin secret which gives full control. It is paramount that these secrets do not leave the backend domain such as your own API. The same goes for privileged admin sessions. If these leak, full control of your catalog might be given to unknown third parties. Starting Sessions The service that governs sessions is called: session.start. 


Consider the following basic server-server session start example:

require_once('lib/KalturaClient.php');
$config = new KalturaConfiguration();
$config->serviceUrl = 'https://platform.vixyvideo.com/';
$client = new KalturaClient($config);
$secret = 'admin secret';
$userId = 'admin@example.com';
$type = KalturaSessionType::ADMIN;
$partnerId = 100;
$expiry = 900;
$privileges = null;
$result = $client->session->start($secret, $userId, $type, $partnerId, $expiry, $privileges);

This will start a session on the Kaltura API running at platform.vixyvideo.com. The $result will contain an admin KS that should be used on consecutive calls to the API. This is only used on server-sever because the KS is kept secret from normal users and only used by automated code on the publisher side.


Consider the following client-server session start example:

require_once('lib/KalturaClient.php');
$config = new KalturaConfiguration();
$config->serviceUrl = 'https://platform.vixyvideo.com/';
$client = new KalturaClient($config);
$secret = 'user secret';
$userId = 'unpriviliged@example.com';
$type = KalturaSessionType::USER;
$partnerId = 100;
$expiry = 900;
$privileges = '';
$result = $client->session->start($secret, $userId, $type, $partnerId, $expiry, $privileges);

This will start a session on the Kaltura API running at platform.vixyvideo.com. The $result will contain a user KS that can be safely used in client facing environments for example when bypassing own infrastructure when uploading files directly to VIXY.


The resulting KS can be added to the client object for subsequent calls by informing the client as follows:

 $client->setKs($result);

Media 

The service that governs the entries in our system is called: media. This service allows for the following: Adding / Updating entry data Deleting entries Adding video content to entries Listing entries When accessing this service it requires a user KS with sufficient user privileges or an admin ks added to the client object already.


Example adding a new entry:

require_once('lib/KalturaClient.php');
$config = new KalturaConfiguration();
$config->serviceUrl = 'https://platform.vixyvideo.com/';
$client = new KalturaClient($config);
$entry = new KalturaMediaEntry();
$entry->name = 'lorem';
$entry->description = 'ipsum';
$result = $client->media->add($entry);

This will create a new entry in your catalog with status: no content. This is because curating and uploading are two different processes. The adding and uploading of video content will be explained later on in the guide.


Example updating an existing entry:

require_once('lib/KalturaClient.php');
$config = new KalturaConfiguration();
$config->serviceUrl = 'https://platform.vixyvideo.com/';
$client = new KalturaClient($config);
$entryId = 'ENTRY ID';
$mediaEntry = new KalturaMediaEntry();
$mediaEntry->name = 'test';
$mediaEntry->description = 'test';
$result = $client->media->update($entryId, $mediaEntry);

This will update a previously created entry with id . This entry id can be fetched by the media.list call or previously cached in your own system.

For the full documentation on the possible media types or a list of all KalturaMediaEntry properties please consult the full documentation.


Example listing all media entries 

There are many use cases where you may want to list the full inventory directly from our API, for example when importing the catalog into your own application or to execute some automated task.

Consider the following example:

$items = array();
$client = [initiate client snippet]

$size = 500;
$i = 0;
do {
  $filter = null;
  $pager = new KalturaFilterPager();
  $pager->pageSize = $size;
  $pager->pageIndex = $i+1;
  $response = $client->media->listAction($filter, $pager);
  foreach ($response->objects as $item) {
    $items[$item->id] = $item;
  }
  $i += 1;
} while ($i * $size <= $response->totalCount)

This will iterate over the media.list at least once, the response always has a totalCount set so it can be used to page over the catalog. Page sizes over 500 are ignored and set to 500.


Uploading video content 

As mentioned before, uploading and content editing are two different processes. Uploading is preferably done in a stateless way using the uploadToken functionality. This is due to the fact that video content is usually very large and interruptions can lead to unhappy customers especially if they have unreliably internet connections. Using the uploadToken service interruptions are observable and upload can be resumed after connectivity has been restored.

The following sequence diagram describes the workflow for a client facing website that has both a javascript frontend and backend api or cms and does not want to stage the uploaded assets on their own infrastructure first.

A description of the steps taken: 

  1. A user initiates an upload in the front-end by selecting a file on a element. 
  2. The frontend informs of the intent to upload a file. During this step extra information or access checking by the website is performed. 
  3. The backend initiates a USER session at VIXY video. This KS will be shared to a non-secret environment so for added security add a special upload user that has only upload rights and start the session for that user. When considering a sensible expiry for the session keep in mind that the token generated in the next step will expire when the session does. 
  4. The backend initiates upload by calling uploadToken.add using the session started in the previous step. 
  5. The backend sends back the user KS(1) and Upload Token(2) to the javascript frontend. The Javascript frontend will start sending File slices to the VIXY API .The following is an extract of the javascript upload at VIXY that uses background Workers.
worker = {
    config: function (config) {
        workerConfig = config;
    },
    start: function () {
        if (!workerConfig) {
            throw  "Please workerConfig this worker first";
        }

        url = workerConfig.host + '/api_v3/';
        worker.next();
    },
    next: function () {
        var resume = sent > 0;
        var final = workerConfig.file.size <= sent + chunkSize;
        if (workerConfig.file.size > sent) {
            worker.upload(workerConfig.file.slice(sent, sent + chunkSize), sent, resume, final);
        } else {
            worker.done();
        }
    },
    result: function (e) {
        if (xhr.readyState !== 4) {
            return;
        }

        if ( xhr.responseText.length == 0 ){
            worker.error('Empty response, internet disconnected?');
            return;
        }

        var result = JSON.parse(xhr.responseText);
        if (result.objectType !== null && result.objectType == 'KalturaAPIException') {
            worker.error(result);
            return;
        }

        worker.success(result);
        return;
    },
    done: function () {
        self.postMessage(['done']);
    },
    error: function (data) {
        self.postMessage(['error', data]);
    },
    success: function (data) {
        sent = parseInt(data.uploadedFileSize);
        self.postMessage(['progress', sent]);
        worker.next();
        return;
    },
    upload: function (blob, sent, resume, final) {
        var data = new FormData();
        data.append('service', 'uploadToken');
        data.append('action', 'upload');
        data.append('format', '1');
        data.append('ks', workerConfig.ks);
        data.append('uploadTokenId', workerConfig.token);
        data.append('fileData', blob);
        data.append('resume', resume);
        data.append('finalChunk', final);
        //data.append('resumeAt', sent);

        xhr = new XMLHttpRequest();
        xhr.open('POST', url, true);
        xhr.onreadystatechange = worker.result;

        xhr.send(data);
    }
};

6. When the upload loop finishes, the frontend informs the backend the upload has been finished and closed.

7. The backend then starts a privileged session that may create media.

8. The backend then creates a new media entry using media.add

9. The backend then adds the finished upload to the media using media.addContent. This will add the content as the source for that entry and kick off the encoding process.


Using advanced security 

There are cases where you - the implementing application - want full control over who gets to see what content. To facilitate this we offer “KS security”. When this option is enabled on the security profile ( settings > acces control ) for your media entry our player will return errors if the embed code lacks a valid KS session string. In short: no playback can start without first generating a valid viewing KS.

The following example generates a viewing KS that is valid for 1 hour only for entry

require_once('lib/KalturaClient.php');
$config = new KalturaConfiguration();
$config->serviceUrl = 'https://platform.vixyvideo.com/';
$client = new KalturaClient($config);
$secret = 'user secret';
$userId = 'unpriviliged@example.com';
$type = KalturaSessionType::USER;
$partnerId = 100;
$expiry = 3600;
$privileges = 'sview:entryid';
$result = $client->session->start($secret, $userId, $type, $partnerId, $expiry, $privileges);

We strongly recommend creating a new read-only user to initiate the viewing sessions for, because otherwise unintended access might be extended to viewers.

The privileges parameter pins the session on that specific entry. No other entry can be viewed by using the same KS as would be the case when you leave it empty. Do not use the admin secret!


Embedding the VIXY player when using KS security

You can get the dynamic embed code from the OVP and add the KS parameter as follows:

kWidget.embed({
         'targetId': 'vidPlayer',
         'wid': '_100',
         'uiconf_id' : '[uiconf]',
         'entry_id' : '[entryid]',
         'flashvars':{ 
              'ks': '[KS]'
         },
});
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us

Related Articles