Page tree
Skip to end of metadata
Go to start of metadata

Summary

The Frequency content can be integrated into your systems through any one of multiple paths. The integration options for Frequency's content and services are as follows:

  • Full Service Integration - A Full Service Integration is the fastest way to share Frequency content with your customer base. A full service Frequency integrations includes the Frequency API services along a Frequency video player. A Full Service Integration is typically a client side integration, but can also include server side integration if a server infrastructure already exist. 
    • Standalone Video Player - The Frequency video player is a full featured player capable of playing all of Frequency's video content, advertisements, and handle ad and video play metrics beaconing. The standalone video player is expected to be the only video player on the client.
    • Shared Video Player - Frequency has a version of the video player that can also operate in a "Lite" or shared mode. When using the Frequency "Lite" video player it can co-exist with other client side video players while still offering all the capabilities of the full Frequency video player, with the exception that it can only play HTML5 supported media types.
  • Partial Service Integration - A Partial Service Integration uses the Frequency API services are used to access video content and its metadata, but used your video player instead of one of the Frequency video player options. A Partial Service Integration can either be client side, server side or a combination of client and server integration.
  • Content only Integration - A Content only Integration is a licensing ingestion process that does not use any of the Frequency services or players.

The question of which integration path to use is significantly influenced by whether you are doing a fresh start implementation or will be integrating into an existing system. A fresh start implementation will will enjoy the head start of a full integration with the Frequency services, yet Frequency has integration options to best support your path to pipeline the Frequency video content into your infrastructure and ultimately clients.  

Full Integration

A full integration with Frequency provides full access to all Frequency service APIs to access video metadata along with various video content personalization and search services. The available Frequency services include:

  • Authentication
  • Guide
  • Collections
  • Intelligence 
  • Personalization
  • User

Added to these capabilities are two full featured video player options, a standalone player or a player capable of playing along side your existing video player.

Standalone Video Player

The standalone Frequency video player can play Frequency and non-Frequency video content. The player has complete advertisement VAST 3.0 support along with ad and video playback metrics beaconing. The standalone video player is the best option if there is not a specialized video player already in the client application. This is because in one step all video and advertisement capabilities are made available to your client app. 

Shared Video Player

With a shared video player architecture there is an existing client video player and possibly its advertisement and beaconing operations that the Frequency video player must play alongside. To play alongside an existing player Frequency offers a "Lite" video player. The "Lite" player has the same advertisement and beaconing support as the standalone Frequency video player, the only difference is that the "Lite" player is built solely on a shared HTML5 video object and can only play HTML5 video object supported media types. In this arrangement the Frequency "Lite" video player plays the Frequency video content and the existing video player can play all non-Frequency content. If you don't have pre-existing specialized video handling, it is better to use the Frequency standalone video player. That is because the standalone player supports a larger diversity of player options and media types such as YouTube or content specific players.

No Player Integration

The no player integration path supports access to all of the Frequency service APIs as in the full integration path options, with the exception that you must handle all video playback, advertisement and beaconing support on your own. This path is best for server side integrations where where the Frequency content is seamlessly blended into your current content delivery infrastructure. 

Content Only Integration

With the content only integration path you get licensed access to the Frequency content assets and raw metadata. The content assets and metadata would then be ingested into your systems.  

Frequency Integration Comparison Table

Integration OptionsFull Integration
(full video player) 
Full Integration
(shared video player) 
No Player IntegrationContent Only Integration
Requires AuthenticationXXX 
Video Discovery APIsXXX 
Video Metadata APIsXXX 
Video PlayerXX  
Shared Video Player X  

Supports Content Supplied Players
(YouTube, Vevo, etc)  

X   
Advertisement PlayXX  
Advertisement BeaconingXX  
Video Metrics BeaconingXX  
Video Ingest   X
Video Metadata Ingest   X

Integration Scenarios

Full Integration with Video Player

The full integration with video player scenario includes the following steps:

  1. Authenticate with Frequency.
  2. Use the Frequency services to access video metadata.
  3. Play videos described in the metadata.

Authentication

Before any Frequency service can be accessed you must be authenticated. The Frequency authentication is a multistep operation. You need to be issued a Frequency SDK key what is used to authenticate all devices used to access the Frequency services. Device authentication is performed as described in the following Javascript code snippet. The code snippets assume the use of a JavaScript REST library. In our case the REST library is a simple XMLHttpRequest wrapper called "rest". The wrapper assumes a success and failure set of function for callbacks to the REST operations.

/// authenticate your device with the Frequency services. In the response 
/// Frequency issues a set of anonymous user tokens.
var payloadDeviceAuth = 
{
   "os":           yourOS,
   "os_version":   yourOSVer,
   "model":        yourModel,
   "manufacturer": yourManufacturer,
   "height":       yourDevResHeight,
   "width":        yourDevResWidth,
   "app_version":  yourAppVersion,
   "company":      yourCompanyName,
   "key":          yourSDKKey,       
   "app_name":     yourAppName
};

rest.post('/api/2.0/auth/device', payloadDeviceAuth, function(response)
{
   /// save the tokens for subsequence Frequency service calls.
   rest.tokenAccess  = response.token.token_access;
   rest.tokenRefresh = response.token.token_refresh;
   rest.deviceId     = response.device_id;
   rest.accountId    = response.account_id;
 
   /// perform authenticated service functions.
}, function(statusCode, statusMsg)
{
   console.error('Error ' + statusCode + ' ' + statusMsg);
});

If you wish for the user state to be shared across multiple devices you could go a step further beyond device authentication and actually authenticate the user within the Frequency system. 

It is important that the auth access token and device id are placed in the request header for all subsequent access of the Frequency services.

Links to the Frequency authentication services documentation:

Authentication 2.0.2

Accessing Video Metadata

The Frequency video metadata and its various query modes, guide, search, rules, etc is then accessed through the Frequency API REST services. A typical Frequency REST call to access the video metadata looks like the following:

// get a channels latest videos.
rest.get('/api/2.0/channel/1937457657634/videos', function(response)
{
   var videos = response;
 
   var video = videos[0];
 
   /// other app operations.
}, function(statusCode, statusMsg)
{
   console.error('Error ' + statusCode + ' ' + statusMsg);
});
 
// search for videos that meet a query.
rest.get('/api/2.0/search/video/query=playoffs', function(response)
{
   var videos = response;
 
   var video = videos[0];
 
   /// other app operations.
}, function(statusCode, statusMsg)
{
   console.error('Error ' + statusCode + ' ' + statusMsg);
}); 

Note: The media url necessary to play a video, along with advertisement support is part of the video metadata returned in the API responses.

Links to the Frequency video metadata services documentation:

Guide 2.0.9

Search 2.0.18

Collections 2.0.2 (deprecated)

Playing Videos

The Frequency video player is a JavaScript object that is standalone component, with the exception that it needs a valid set of authentication tokens to support its beaconing operations. Because of this the authentication shown above must be performed before the Frequency video player is created and used. The life span of the Frequency video player is up to you. Typically it is created once and kept alive for the life of the app, but some applications only keep the player alive for the duration of a Frequency video playlist. In these cases once the playlist has completed the player is destroyed and then recreated for the next playlist. Scenarios that require a short lived player are rare and only exist because of underlying software/hardware requirements that can sometimes be found in set top box applications.

The following code snippet shows how to construct the Frequency video player and then use it to play a video:

var player = new Frequency.Player(
{
   session:
   {
      'X-Frequency-Auth': rest.accessToken,
      'X-Frequency-DeviceId': rest.deviceId,
      'account_id': rest.accountId
   }
});
 
/// register for player events.
player.addEventListener('onStateChange', function(state)
{
   /// state change handlers.
});
 
/// load and play the video. This call assumes the video autoplay flag is set.
player.load(video); // notice the complete video object that was access above is passed to the player.
 
/// if the autoplay flag is not set then the following call would need to be 
/// performed after the video load has be received through the onStateChange handler.
player.play();

Links to the Frequency video player documentation:

Javascript Video Player

Full Integration with Shared Video Player

With a shared video player architecture the client has two video players, the existing client video player and the Frequency "Lite" video player. The Frequency video player plays the Frequency video content and the existing video player can play all non-Frequency content. This path is taken if the client app has an existing player for handling specialized content, advertisement or beaconing support. If specialized video handling does not pre-exist it is better to use the Frequency dedicated video player. That is because the dedicated player supports more media types than the shared "Lite" video player.

In a shared video player architecture the client infrastructure has its own HTML5 based video player. Since the Frequency "Lite" player also uses the HTML5 video object, both can share the HTML5 video object by both using the same video element id. A typical client registers for video playback events to mark playback start, progress and end. The only difficulty in a shared player architecture is insuring that the client app uses the video playback event correctly. If advertisements are not played events can be registered through the existing video player, ignoring the "Lite" player events. When advertisements are played with the Frequency "Lite" player it is required for the "ended" video player event be switched from the existing player to the Frequency "Lite" player. This is because when playing advertisements the Frequency player will only send video end events when the requested video has finished playing and not at the end of advertisement segments. The remainder of the standard HTML5 video events can be shared seamlessly between the client video players.

The following code snippet describes how to create a shared video player configuration and how to switch the video player "ended" event from one player to the next.

 

// the exist HTML5 based video player.
var playerHTML5 = document.getElementById('myPlayer');
 
var video = videos[0]; // the list of videos from a Frequency API or other source.
 
// register player events.
playerHTML5.addEventListener('error'), onError);
playerHTML5.addEventListener('loadedmetadata'), onMetaLoad);
playerHTML5.addEventListener('timeupdate'), onTimeUpdate);
playerHTML5.addEventListener('ended'), onEnded);    // This is the event that will have to be swapped.
 
// play a video through the HTML5 player.
playerHTML5.src = video.media_url;
playerHTML5.load();

/// somewhere else in the client where Frequency video content is played.
/// ---------------------------------------------------------------------
// use the Frequency player to play a video with an ad.
var playerLite = new Frequency.PlayerLite(document.getElementById('myPlayer'),
{
   session:
   {
      'X-Frequency-Auth': rest.accessToken,
      'X-Frequency-DeviceId': rest.deviceId,
      'account_id': rest.accountId
   }
});

// deregister the "ended" event and register the same event with the "Lite" player.
playerHTML5.removeEventListener('ended'), onEnded);
playerLite.addEventListener('ended'), onEnded);    

// play video through player lite.
video.autoplay = true;
playerLite.loadVideo(video);

// once finished playing Frequency videos and before the existing player used again destroy the "Lite" player.   
playerLite.removeEventListener('ended'), onEnded);    
playerLite.clear();
playerLite = null;

Links to the Frequency video player documentation:

Javascript Video Player

No Player Integration

The no player integration path is a simplification of the above scenarios. Frequency services are used to access video metadata as shown in the above scenarios and your own player is used to play the video content. In this scenario you are responsible for all advertisement and video metrics beaconing. To perform the Frequency required beaconing you would need to authenticate as shown above and post beaconing events using the Frequency activities services. This is done as follows:

var payload =
{
   video_id: "345829374598348";
};
 
rest.post('api/2.0/activities/video/start', payload, function(response){}, function(statusCode, statusMsg)
{
   console.error('Error ' + statusCode + ' ' + statusMsg);
});
 
// this can be simplified to the following:
rest.post('api/2.0/activities/video/start', {video_id: "345829374598348"}, function(response){}, function(statusCode, statusMsg)
{
   console.error('Error ' + statusCode + ' ' + statusMsg);
});

Links to the Frequency video Activities services documentation:

Activities 2.0.1

Content only Integration

There is not a formal integration procedure for a content only integration. This could be a one time video metadata dump with or without periodic metadata updates. When a content only integration is considered all details and steps to the integration would have to be negotiated.

 

  • No labels