Kaltura Live Ad Stitching Integration

Printer-friendly version
Audience / Tech Expertise: 

Architecture

When Kaltura ad stitching is enabled, the Kaltura 'play-server' cloud manages all client HLS manifest and segment requests. This enables the swapping of individual segments with respective alternate pieces of content. Ads are configured against the Kaltura Ad cuepoint API, or represented directly on the ingest stream. Ad events include a VAST ad tag URL. After the play server reaches a time that includes an ad, a VAST request is made on the server to retrieve ads for each client that is consuming the stream. Ad tags should be configured with respective substitutionsas described in the Integrating Kaltura with VAST adTag URL article.



Configuration

Configuring Ad Stitching Ads via the API  

To allow Kaltura to push ads, the stream must go through Kaltura. Kaltura requires a valid Live stream entry to monitor when the ads should be stitched.

Monitoring the ads' timing is done by watching for any new cuePoints that are being associated with the live stream entry in Kaltura. The cuePoint holds within in, all the information that Kaltura requires to stitch the ad.

To add new cue point's to Kaltura, you should execute a cuePoint->add a call where the type of the cuePoint being added is "KalturaAdCuePoint".

Mandatory parameters for this call are: 

  • entryID - The entry ID associated with the live stream.
  • triggeredAt/startTime - Only one of these fields is required. triggeredAt indicates the absolute time when the ad should be stitched and where, as the startTime is an offset from the beginning of the stream.
  • sourceUrl - Indicates the ad provider URL.
  • duration - The duration of the ad.  (milliseconds).
  • adType - Should be set to 'VIDEO'.

Optional parameters:

  • Title - Textual identifier of the cue point inserted.

Sample php Integration Code

<?php
    //Require Mandatory Classes
    error_reporting ( E_ALL );
    echo "pre-require..." . PHP_EOL;
    require_once (dirname ( __FILE__ ) . '/php5/KalturaClient.php');
     
    //Validate Input Count
    if (count($argv) < 6)
    {
        die ("Usage: [Partner_ID] [KS] [Entry_id] [Ad_Triggered_At] [Ad_Source_Url] [Cue_Point_Title] [Ad_Duration]\n");
    }
     
    //Get Input Params From User
    $partnerId = $argv[1];
    $ks = $argv[2];
    $entryId = $argv[3];
    $adTriggeredAt = $argv[4];
    $adSourceUrl = $argv[5];
    $cuePointTitle = $argv[6];
    $adDuration = $argv[7];
     
    //Create new config & client
    $config = new KalturaConfiguration($partnerId);
    $config->serviceUrl = 'http://www.kaltura.com/';
    $client = new KalturaClient($config);
    $client->setKs($ks);
     
    //Add The New Ad Cue Point
    echo "Adding Ad Cue Point Using The Following Input:\n EntryID = [$entryId]\n Triggered At = [$adStartTime]\n Ad Source Url = [$adSourceUrl]\n ad Duration = [$adDuration] \n";
    $cuePoint = new KalturaAdCuePoint();
    $cuePoint->entryId = $entryId;
    $cuePoint->triggeredAt = $adTriggeredAt;
    $cuePoint->sourceUrl = $adSourceUrl;
    $cuePoint->adType = 1; //VIDEO
    $cuePoint->title = $cuePointTitle;
    $cuePoint->duration = $adDuration;
    $cuepointPlugin = KalturaCuepointClientPlugin::get($client);
    $result = $cuepointPlugin->cuePoint->add($cuePoint);
    echo "Cue Point Created With ID [{$result->id}]\n";
     
    echo "Done! :) \n"
?>

Configuring Ad Stitching Ads via in-stream Ad Events

Stream ad events require custom configuration.

Configuring UiConf Player

Kaltura ad stitching works against the same UiConf player identifiers as the Kaltura Universal Studio players. This enables consolidating ad stitching logic against the same player JSON that drives more feature rich player embeds. The player "VAST" configuration can be configured in the Kaltura Universal studio. You can use different players for web embeds than those used for ad stitching, but note they are managed in the same way with the Universal Studio Player.  

To enable ad tracking by the player and the ad stitching server, you should set trackCuePoints to true in the player JSON configuration. You can do this in one of the following ways:

  • Via the KMC:
    1. Go to the Studio tab.
    2. Edit the player you want to track Kaltura stitched ads.
    3. Select the Monetization tab and open the VAST configuration.
    4. Turn on the "Track cue points" flag.
  • Via the API:
    • In the player config, add the the following line ' "trackCuePoints": true '. This should be added under plugins–>vast section.
      Additionally you must enable the "playServerUrls" plugin.
      To do so:
    • Go to the Ui vars custom plugins section add "playServerUrls.plugin" : true and "playServerUrls.enabledOn" :  "all" uiVars 

Consuming the Ad Stitching URLS 

Via playManifest URLs

Play-server URLs work against the standard Kaltura playMainfest URLs with the addition of a UiConf-id for player configuration. Here is an example URL with identification of standard identifiers: 

http://<serviceHost>/p/<partnerIdValue>/playManifest/format/applehttp/entryId/<entryIdValue>/uiConfId/<uiConfIdValue>/usePlayServer/1/a/playlist.m3u8

Parameters:

entryId - Entry Id to play

uiConfId - UI Conf id, if you want to use an Ad stitching server you should turn on the vast.trackCuePoints feature in your UI Conf.

usePlayServer - Set to 1 if the Ad stitching server should be used.

Additional Parameters that can be Passed on Flashvars:

sessionId- Optional, identifies the unique session id for the specific user. If the sessionId is not passed it is generated by the play server, see 'SessionId concept and Generation' for more details.

Via direct play server URLs (for Roku)

Play-server URLs can be accessed directly as in the following example:

http://<playServerHost>/p/<partnerIdValue>/master/manifest/entryId/<entryIdValue>/uiConfId/<uiConfIdValue>/sessionId/<sessionIdValue>/?url=<originalLiveStreamUrl>/playlist.m3u8

Parameters:

entryId - Entry Id to play

uiConfId - UI Conf id, if you want to use an Ad stitching server you should turn on the vast.trackCuePoints feature in your UI Conf.

sessionId- Optional, identifies the unique sessionId for the specific user. If the sessionId is not passed, it will be generated by the play server. See  Session Id Concept and Ceneration for more details.

url - Original live stream maseter URL.

SessionId Concept and Generation

The SessionId identifies the unique user session against the play server and allows the play server to manage ads and beacons per user. It is initialized in the master/manifest request passed to the play server. The sessionId can be either passed as a parameter or generated by the play server.

If the sessionId is not passed as a parameter the play server will generate a new sessionId every time the new call is performed for the master/manifest request. This is usually done when the player is refreshed. 

Generation: You will need to generate a random number/string

Nodejs example: use Math.random()

PHP example: use uniqid()

 

Document type: 
(12169 reads)