Customizing the Player Menu's Additional Media (Related, Newest, and Most Viewed Videos)

Standard Video Cloud players have an Info screen, launched from the menu button. By default, the Info screen of the Video Cloud menu shows three sets of additional videos that are automatically retrieved for the publisher's account using the same search methods exposed by the Flash-only Player API. These are accessed by tabs in the menu screen labeled "Related Videos", "Most Viewed" and "Newest".

The Video Cloud Flash-only Player API includes a number of methods that enable you to customize the media that appears within the Info screen of the Video Cloud menu. This topic describes how you can take advantage of this functionality for Flash players only. This sample works for the Flash version of the Video Cloud player only. Video Cloud supports two APIs for developing customizations and dynamic solutions for their players: the Flash-only Player API, for solutions for Video Cloud Flash players, and the Smart Player API for solutions for smart players, those players that serve Flash versions of the Video Cloud player where supported, and otherwise serve HTML versions. For more on creating dynamic solutions for smart players, see Using the Smart Player API.

The MenuModule in the Flash-only Player API offers a way to be informed when these videos are to be requested and populated within the menu screen through a callback function passed to the player. You can choose to replace or append lists of videos to those shown in the menu screen when this callback is invoked. The methods introduced to support this functionality are available in both the ActionScript and JavaScript APIs.

Player showing the additional media controls

The Additional Media methods

These methods can be found in the MenuModule of the Flash-only Player API:

callbackFunction

/** 
* Sets the callback for when additional media needs to be requested for the current media
* in the player. This additional media is displayed in the Video Cloud menu Info screen. 
* This function should have the following signature: 
* 
* public function callbackFunction(type:String, media:MediaDTO=null):Boolean 
* 
* The Boolean return value represents if this call will be handled (true) or if the player
* should default to its own methods (false). If null is passed for the callback, then the 
* default logic of the menu is used for fetching of additional videos.
* If null is passed for the types, then the default tabs are used in the Info menu, "Related 
* Videos", "Most Viewed" and "Newest".
* 
* @param  The function that should be called to get additional media for the current media. 
* @param  The types of additional media that can be selected for the current media. An array of strings. 
* If nothing is passed, then the default types in the player are used, RELATED_VIDEOS,  
* MOST_VIEWED_VIDEOS, NEWEST_VIDEOS. 
*/ 
public function setAdditionalMediaCallback(callback:Function, types:Array=null):void;

setAdditionalMediaForType

/** 
* Sets the additional media to display for a specific type for the current media in
* the player. 
* This should be an array of MediaDTOs. 
* 
* @param  The array of MediaDTOs to display for the given type. 
* @param  The type that this array of media represents. 
*/ 
public function setAdditionalMediaForType(media:Array, type:String):void;

getAdditionalMediaForType

/** 
* Returns the additional media loaded for the given type. 
* This should be an array of MediaDTOs. 
* 
* @param  The type that this array of media represents. 
* 
* @return  The array of MediaDTOs loaded for the given type. 
*/ 
public function getAdditionalMediaForType(type:String):Array;

getMediaInGroupAsynch

There is also one additional and related method added to the ContentModule of the Flash-only Player API:

/** 
* Fetches multiple MediaDTOs from server, returning them in an array. 
* 
* @param  The IDs of the media to retrieve and place in an array. 
*/ 
public function getMediaInGroupAsynch(ids:Array):void;

Using the Additional Media methods

The following steps detail the basic process for taking advantage of this functionality.

Call setAdditionalMediaCallback() on the MenuModule and pass in the function that you want called when additional media is to be requested. This will occur whenever the video in the player changes, or a new tab is selected in the Info menu screen. If you wish to override the tabs that appear in the Info menu screen, you can pass an array of the desired tab names as a second parameter. You can also use the constants of MenuModule to add any new lists within the screen, as in the following:
```
// ActionScript 
menuModule.setAdditionalMediaCallback(myCallbackFunction,
    ["Favorites", MenuModule.RELATED_VIDEOS]); 
 
// JavaScript 
menuModule.setAdditionalMediaCallback(myCallbackFunction,
    ["Favorites", BCMenuAdditionalMedia.RELATED_VIDEOS]);
```
If you do not pass in a second parameter, the default tabs appear in the Info menu screen.
The callback function specified in the previous step should accept a String as a first parameter. This is the type of additional media that has been requested, taken from the selected tab in the Info menu screen. The second parameter should be a MediaDTO, and this will be the current media in the player for which the additional media should be fetched. The callback method should return a Boolean value that specifies whether the callback function is handling the request (true) or whether the player should handle the request for the type, if it is one of the defaults.

As an example of how to set up a function to make a request to an external server if the type is RELATED_VIDEOS, instead of using the Video Cloud default search, consider the following ActionScript code:
```
// note that this example would require used of the Flash-only Player API SWC
// and extending of the CustomModule class 
 
override protected function initialize():void { 
  var menuModule:MenuModule = player.getModule(APIModules.MENU) as MenuModule; 
  menuModule.setAdditionalMediaCallback(getAdditionalMedia); 
} 
 
public function getAdditionalMedia(type:String, media:MediaDTO):Boolean { 
  if (type == MenuModule.RELATED_VIDEOS) { 
    requestRelatedForMedia(media.id); 
    return true; 
  } 
  return false; 
} 
 
private function requestRelatedForMedia(id:Number):void { 
  // code to call external server for list of videos IDs
  // using third party recommendation engine 
}
```
In this code, a callback is set for when additional videos need to be requested. No new types are passed, so the defaults will be used. If the type passed to the callback is RELATED_VIDEOS, the callback invokes a custom method that will request Video Cloud video IDs from a recommendation engine and a value of true is returned so that the player knows this external function is handling the request. For all other types, a value of false is returned, which tells the player to use the Video Cloud search algorithms.

If you have a set of Video Cloud IDs returned through some third party system, you need to load the actual media metadata into the player in order to display the media in the Info menu screen. The ContentModule's getMediaInGroupAsynch() method allows you to pass an array of IDs to the player that will result in a single request for all of the metadata. The following addition to the sample code shows the request made to the player.

// note that this example would require used of the Flash-only Player API SWC
// and extending of the CustomModule class 
 
override protected function initialize():void { 
  var menuModule:MenuModule = player.getModule(APIModules.MENU) as MenuModule; 
  menuModule.setAdditionalMediaCallback(getAdditionalMedia); 
} 
 
public function getAdditionalMedia(type:String, media:MediaDTO):Boolean { 
  if (type == MenuModule.RELATED_VIDEOS) { 
    requestRelatedForMedia(media.id); 
    return true; 
  } 
  return false; 
} 
 
private function requestRelatedForMedia(id:Number):void { 
  // code to call external server for list of videos IDs using third party
  // recommendation engine 
  
// a successful request is assumed to call onRelatedRequestComplete()
} 
 
private function onRelatedRequestComplete(event:Event):void {
   // this assumes a variable ids is populated by values accessed from the response       var ids:Array = [];   var contentModule:ContentModule = player.getModule(APIModules.CONTENT) as ContentModule;
       contentModule.addEventListener(ContentEvent.MEDIA_COLLECTION_LOAD, onMediaCollectionLoad);
        contentModule.getMediaInGroupAsynch(ids);
   }
   private function onMediaCollectionLoad(event:ContentEvent):void {  }

Once the player has completed loading of the metadata needed to display the desired list of media in the Info menu screen, setAdditionalMediaForType() can be called to pass these to the player for rendering in the menu, as the following additional code demonstrates.

// note that this example would require used of the Flash-only Player API SWC
// and extending of the CustomModule class 
 
override protected function initialize():void { 
  var menuModule:MenuModule = player.getModule(APIModules.MENU) as MenuModule; 
  menuModule.setAdditionalMediaCallback(getAdditionalMedia); 
} 
 
public function getAdditionalMedia(type:String, media:MediaDTO):Boolean { 
  if (type == MenuModule.RELATED_VIDEOS) { 
    requestRelatedForMedia(media.id); 
    return true; 
  } 
  return false; 
} 
 
private function requestRelatedForMedia(id:Number):void { 
  // Code to call external server for list of videos IDs using third party 
  // recommendation engine. A successful request is assumed to call
  // onRelatedRequestComplete() 
} 
 
private function onRelatedRequestComplete(event:Event):void { 
  // this assumes a variable ids is populated by values accessed from the response 
  var ids:Array = []; 
  var contentModule:ContentModule = player.getModule(APIModules.CONTENT) as ContentModule; 
  contentModule.addEventListener(ContentEvent.MEDIA_COLLECTION_LOAD, onMediaCollectionLoad); 
  contentModule.getMediaInGroupAsynch(ids); 
} 
 
private function onMediaCollectionLoad(event:ContentEvent):void { 
  var mediaIds:Array = event.mediaCollection.mediaIds;
   var mediaDTOs:Array = [];
   for each (var id:Number in mediaIds) {
      mediaDTOs.push({id:id});
     }
   var menuModule:MenuModule = player.getModule(APIModules.MENU) as MenuModule;
   menuModule.setAdditionalMediaForType(mediaDTOs, MenuModule.RELATED_VIDEOS);
}

The ContentEvent passed to the MEDIA_COLLECTION_LOAD handler will hold a playlist containing the video IDs loaded in the request. The call to setAdditionalMediaForType() expects DTOs, though. However, the player is intelligent enough that as long as the ID for the video is passed in an object, the full MediaDTO player-side will be used. Therefore, the code above creates an array of objects, each containing an id property, just like a MediaDTO instance. This array is passed to the MenuModule in the setAdditionalMediaForType() call along with the RELATED_VIDEOS type. If the player is still displaying the Info menu screen, this collection will be rendered within the menu.

You can download a full listing of both ActionScript and JavaScript implementations.

Video Cloud

App Cloud

Resources