CMS Integration Guidelines

by | Sep 24, 2020 | Integrations, Players

Every organization does things differently, which is why it’s important that our customers can mix and match their CMS providers with Field59’s video systems. This flexibility gives our clients the most freedom to integrate online video within their existing web publishing workflows or as part of a newly formed web publishing partnership.

To accommodate our clients’ varied needs, we’ve built our video platform to work from the ground-up as an independent system that can plug into any CMS. Using our native MRSS syndication feeds along with our flexible API, we’ve made it easy for developers to plug our code into their websites.

If you have access to write and modify your own templates, you can implement Field59’s video player following some of the sudo code examples provided.

Please note in any example embed codes and URLs below, the omission of “http” or “https” from the URLs is purposeful. The Field59 player will check the page on which it is being embedded, and determine whether it needs to serve as secure or insecure, depending on the application environment in which it is being rendered.

 

 

Video Keys

Video keys, or keys, are unique identifiers that reference individual video packages, playlists or other assets (live events, live channels) generated by the Manager Application. Each key is comprised of 40 characters. It is not a reference to the URL where the video is hosted, but rather a package of data that contains (in the case of a video) the source video, other transcoded versions of the source video and meta data describing the video properties.

Example key:

b41ddf4096cb8e628227eac565d6bbd28966dfa9

A method for integrating video into a CMS is to add a key field to your most commonly used content types (Story, Blog, etc.). Content producers can then paste a key into that field when publishing a story.

You will need to add code to verify if the field is populated and is 40 characters long. It is a good practice to add code to your key check that removes any white space. Once verified, you can have the video player display or maybe just the thumbnail image.

Code Example:

## Set a variable $key
## Trim any white space from the key field
#set($key = $string.trim($story.key))
## If $key is not empty and is 40 characters long, do something
#if($key != "" && $key.length() == 40)
	## SOMETHING
#end

Embed Codes

Embed codes are quick and easy ways to view your video or playlist on your website. An embed code is a simple JavaScript tag that can be pasted into a body of a story or blog.

For more advanced implementations, you may want to have your CMS automate the way an embed code is constructed. By doing this, you can allow more control of how your video content is displayed (or not displayed). This is especially valuable when you are re-using your content in RSS or other types of feeds that may not display properly with JavaScript embed codes.

Video Embed Code

The video embed code follows a simple URL pattern and uses the following elements:

  • Player Source URL – //player.field59.com/v4/vp/
  • User Identification – This will be the identification given to your publishing account and will be the same for all videos and playlists. This should match your Field59 account name. This data can come from a root-level field that can be manually entered. For broadcast clients, it is usually your call letters. It is not case-sensitive.
  • Key – This is unique for each video.

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY'></script>

When combined with a key check, the embed code can be scripted to automatically be generated on a page.

Code Example:

## Set a variable $key
#set($key = $string.trim($story.key))
## Set a variable $ident.
#set($ident = $host.identification)
#if($key != "" && $key.length() == 40)
	<script src='//player.field59.com/v4/vp/${ident}/${key}'></script>
#end

Player Display Size Parameters

Each video item uses a video player that is assigned to it. If a custom player has not been assigned, the default player will be rendered.

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY/w=YOUR_WIDTH;h=YOUR_HEIGHT'></script>

Code Example:

#set($key = $string.trim($story.key))
#set($ident = $host.identification)
#set($playerWidth = 600)
#set($playerHeight = 400)
#set($paramString = "w=$playerWidth;h=$playerHeight")
#if($key != "" && $key.length() == 40)
	<script src='//player.field59.com/v4/vp/${ident}/${key}/${paramString}'></script>
#end

Player Image Parameter

A Field59 user can assign a custom thumbnail image to a video asset using the Video Manager interface. Additionally, you have the option to pass information to the video player embed code to display images from other sources such as your CMS.

  • Thumbnail Image – /thumb=

The /thumb parameter uses a Base64 encoded URL. A sample Base64 encoded string looks like this:

aHR0cHM6Ly9zMy5hbWF6b25hd3MuY29tL2JpbS1zdG9yYWdlL0JJTVZJRElORk8vdGhlX2NoZWF0LmpwZw==

Once encoded, the player embed code will require you to trim any trailing “=” characters.

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY/thumb=YOUR_BASE64_ENCODED_STRING'></script>

Code Example:

#set($encoded=$util.base64Encode($story.image.url))
#set($encoded=$string.trim($encoded))
#set($enc1=$string.replaceAll($encoded, "+", "-"))
#set($enc2=$string.replaceAll($enc1, "/", "_"))
#set($encoded=$string.replaceAll($enc2, "=", ""))
#set($paramString = "thumb=${encoded}")
<script src='//player.field59.com/v4/vp/${ident}/${key}/$/${paramString}'></script>

Player Key Parameter

Custom players are configured in the Setup tab of the Video Manager. If you have a custom player that you have already configured, you are able to apply the player key as a parameter in the embed code.

  • Custom Player Key – /player=

To get the player key, you will need to click into the player setup detail page and grab the 24 character identifier from the detail URL.

Example URL:

http://manager.field59.com/setup/edit/YOUR_24_CHARACTER_PLAYER_KEY

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY/player=YOUR_24_CHARACTER_PLAYER_KEY'></script>

Autoplay Parameter

By default, autoplay is set to false on all players unless specified as a custom player. To override this behavior, use the autoplay parameter.

  • Autoplay – /autoplay=true

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY/autoplay=true'></script>

Combining Parameters

When implementing a player embed code, it is possible to combine multiple parameters. To do this, use the “;” to separate the parameters.

Format Example:

<script src='//player.field59.com/v4/vp/YOUR_IDENTIFICATION/YOUR_VIDEO_KEY/w=YOUR_WIDTH;h=YOUR_HEIGHT;thumb=YOUR_BASE64_ENCODED_STRING'></script>

 

Div Targeting Via JavaScript

If you add a snippet of JavaScript to a page:

<script>
var field59 = field59 || {};
field59.ipo = {
   "global" : {
       "targetdiv":"idofdiv"
   }
}
</script>

The player on that page will load itself into the div with an ID specified. However, since it’s a global variable, all players will load themselves into that div. As this may be problematic, we also support specifying which player on the page should load into that div, by specifying the key in the JavaScript:

<script>
var field59 = field59 || {};
field59.ipo = {
   "dockey123445667788999008643" : {
       "targetdiv":"idofdiv"
   }
}
</script>

 

Playlists

To embed a playlist on your website is similar to how individual videos are embedded. Both “smart” and “manual” playlist types follow a simple URL pattern and uses the following elements:

  • Player Source URL –  http://player.field59.com/v4/playlist/
  • User Identification – This will be the identification given to your publishing account and will be the same for all videos and playlists. This should match your Field59 account name. This data can come from a root-level field that can be manually entered. For broadcast clients, it is usually your call letters. It is not case-sensitive.
  • Key – This is unique for each playlist. Video keys do not work with playlist keys, so you should make sure you are able to differentiate them in some naming convention in your system.

When combined with a key check, the playlist embed code can be scripted to automatically be generated on a page.

Format Example:

<script src='//player.field59.com/v4/playlist/YOUR_IDENTIFICATION/YOUR_PLAYLIST_KEY'></script>

Code Example:

## Set a variable $key
#set($playlistKey = $string.trim($story.playlistKey))
## Set a variable $ident.
#set($ident = $host.identification)
<script src='//player.field59.com/v4/playlist/${ident}/${playlistKey}'></script>

 

Playlist MRSS

MRSS is short for Media RSS, an extension of the RSS format used for syndicating multimedia files (audio, video, image) in RSS feeds. When you create a playlist, a MRSS feed is automatically created. It follows a simple URL pattern pattern and uses the following elements:

  • Player Source URL –  //player.field59.com/v4/feed
  • User Identification – This will be the identification given to your publishing account and will be the same for all videos and playlists. This should match your Field59 account name. This data can come from a root-level field that can be manually entered. For broadcast clients, it is usually your call letters. It is not case-sensitive.
  • Key – This is unique for each playlist.

The MRSS feeds support RSS version 2.0. Full specifications can be found here: http://video.search.yahoo.com/mrss. MRSS video feeds are a good way for you to syndicate your video to other providers if needed.

Code Example:

## Set a variable $key
#set($playlistKey = $string.trim($story.playlistKey))
## Set a variable $ident.
#set($ident = $host.identification)

#set($myFeed = $rss.channel("//player.field59.com/v4/feed/${ident}/${playlistKey}"))
#foreach($item in $myFeed.items)
	<p><a href="$item.link">$item.title</a><br/>$item.description</p>
#end

 

Images

When integrating the video player into your CMS, there will be cases when you need to display the isolated video image without rendering the player or playlist. To do this you will need to call out to the Field59 Predictable URL Service.

To display a single video without resizing, you will need to set the image source root URL to: //redirect.field59.com/video/thumb/. Add the video key and optional MIME type of .jpg. This will automatically display the full sized image associated with the video.

Format Example:

<img src='//redirect.field59.com/video/thumb/YOUR_VIDEO_KEY.jpg' />

Code Example:

#set($key = $string.trim($story.key))
#set($storyimgobj = "//redirect.field59.com/video/thumb/$!{key}.jpg")
<img src="$storyimgobj" alt="Video Image" title="Video Image">

Resize

If you need to display a resized image. Use the same format, but add height and width properties to the url. Height and width are required to be calculated ahead of time.

Format Example:

<img src='//redirect.field59.com/video/thumb/YOUR_VIDEO_KEY/w(YOUR_WIDTH)/h(YOUR_HEIGHT).jpg' />

Code Example:

#set($key = $string.trim($story.key))
#set($height = "150")
#set($width = "250")
#set($storyimgobj = "//redirect.field59.com/video/thumb/$!{key}/w$!{width}/h$!{height}.jpg")
<img src="$storyimgobj" alt="Resized Video Image" title="Resized Video Image">
 

Predictable URL Service

The instructions described above for retrieving a predictable URL for an image is just one of several files that can be achieved using the Predictable URL Service:

Video formats

  • redirect.field59.com/video/{key} returns the MP4 format for the video.
  • redirect.field59.com/video/{key}.m3u8 returns the HLS format for the video.
  • redirect.field59.com/video/{key}.f4m returns the HDS format for the video.
  • redirect.field59.com/video/{key}.mpd returns the DASH format for the video.
  • Specific outputs can also be requested for any of the above formats via an additional redirect.field59.com/video/{size}/{key}
    • Accepted {size} values: 240, 360, 480, 576, 720, 1080
    • This will return only the single size specified
    • If the video has not been transcoded into requested size (per account settings), response will be 404 error message.

Images

  • redirect.field59.com/video/thumb/{key} returns the image for the video.
  • Use /w and/or /h parameters as described above in the Images section to set specific sizes as needed.

Captions

  • redirect.field59.com/video/captions/{key} returns the WebVTT captions format for the video.
  • You can optionally add .vtt to the end of this URL format (redirect.field59.com/video/captions/{key}.vtt)

 

Share This