Maintaining Deep-linking Capabilities with linkBaseURL

In this topic you will learn how to utilize the linkBaseURL player configuration parameter, as well as the getLink() and setLink() methods of the Flash-only Player API's Social Module to support deep-linking to your players.

The steps outlined in this topic are for Flash based players and will not work in HTML5 players.

The "Get Link" feature in a player is a key viral distribution technique for your videos. Altering the URL used in the "Get Link" menu page can be accomplished in a number of ways. One approach relies on a player configuration parameter named linkBaseURL. That approach is described in the Customizing the Link URL help topic.

The problem with using the linkBaseURL player configuration parameter is that the player cannot know what environment it is published in, so it does not automatically append the playlist ID and video ID to the URL in order to support deep-linking. It is up to you as the publisher or developer to recreate this functionality so it works properly with your implementation. This article aims to explain that process.

The code in this article utilizes the linkBaseURL player configuration parameter, as well as the getLink() and setLink() methods of the Flash-only Player API's Social Module. You can download a zip file that includes the full source code for this example. Click here to see this project live.

For starters, specify the base URL of your player in the JavaScript publishing code:

<script language="JavaScript" type="text/javascript" 
    src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>
<script type="text/javascript" src="http://admin.brightcove.com/js/APIModules_all.js"></script>
 
<object id="myExperience" class="BrightcoveExperience">
  <param name="bgcolor" value="#FFFFFF" />
  <param name="width" value="798" />
  <param name="height" value="465" />
  <param name="playerID" value="1620628663" />
  <param name="publisherID" value="1370912864"/>
  <param name="isVid" value="true" />
  <param name="isUI" value="true" />
  <param name="linkBaseURL" value="http://files.brightcove.com/dev/linkBaseURL/index.html" />
</object>

Remember: before you can use the Flash-only Player APIs in a player, you need to enabled the APIs for the player in the Video Cloud Studio Publishing module. You also need to add the APIModules_all.js script element to the player publishing code, as shown above.

To interact with the Flash-only Player APIs via JavaScript, you need to set up the standard global variables, write a onTemplateLoaded method, get references to the player and its modules, and set up event listeners for templateReady and mediaChange. If you are new to working with the JavaScript APIs, this process is described thoroughly in the Using JavaScript with the Player API help topic.

var player;
var video, content, exp, menu, ads, social;
var tabBar;
 
function onTemplateLoaded(pPlayer) {
 
     player = bcPlayer.getPlayer(pPlayer);
 
     video 	= player.getModule(APIModules.VIDEO_PLAYER);
     content = player.getModule(APIModules.CONTENT);
     exp 	= player.getModule(APIModules.EXPERIENCE);
     menu 	= player.getModule(APIModules.MENU);
     ads 	= player.getModule(APIModules.ADVERTISING);
     social = player.getModule(APIModules.SOCIAL);
 
 
     exp.addEventListener(BCExperienceEvent.TEMPLATE_READY, onTemplateReady);
     video.addEventListener(BCMediaEvent.CHANGE, onMediaChange);
 
}

templateReady handler

Next you will need to define the templateReady handler. This function executes exactly 1 time when the player is fully initiated and ready to be interacted with. It gets a reference to the tabBar component of the player and performs the initial URL update for the default loaded video by passing the current Video ID and Playlist ID to a custom function named updateLink that will be defined later on in this article.

function onTemplateReady(e) {
 
     tabBar = exp.getElementByID("playlistTabs");
     updateLink(video.getCurrentVideo().id, tabBar.getSelectedData().id);
 
}

Note that this example assumes that you're working with a multi-playlist player that has a tabBar component. If you instead are using a single playlist player, your player might have a List or TileList component instead, and you would get the playlist id from the player publishing code parameters.

function onTemplateReady(e) {   
  updateLink(video.getCurrentVideo().id, exp.getPlayerParameter("@videoList"));

}

mediaChange handler

You will also need a mediaChange handler that executes every time a new video is loaded in the player:

function onMediaChange(e) {
 
     if(exp.getReady()) { // If template is Ready
 
     // Because TemplateReady has already fired we can now access the
     // currentVideo and currentPlaylist from the tabBar module
 
     updateLink(video.getCurrentVideo().id, tabBar.getSelectedData().id);
 
     }
 
}

updateLink function

Lastly, define the updateLink function that actually compiles the new URL based on the currently loaded video and currently selected lineup. It retrieves the current URL, trims off any existing URL parameters, and then appends the new ones. I've used the URL keys that the player is expecting, bclid and bctid, but you can easily change these key names if your project requires different keys.

function updateLink(videoId, playlistId) {
 
	// Brightcove players published using the standard JavaScript publishing code 
	// automatically listen for bclid and bctid in order to select featured items. 
	// If your application is setup in another format, such as ActionScript, you can
	// choose to alter these key names to something compatible with your application.
	// Your application will be responsible for properly setting the featured content.
 
	var playlistKey = "bclid";
	var videoKey = "bctid";
 
 
	var currentLink = social.getLink();
 
	// Get the current URL and remove any existing URL parameter
	if(currentLink.indexOf("?") != -1) {
		currentLink = currentLink.substring(0,currentLink.indexOf("?"));
	}
 
	var newLink = currentLink + "?" + playlistKey + "=" + playlistId + "&"
      + videoKey + "=" + videoId;
	social.setLink(newLink);
 
}

Now this player will always have an up-to-date URL available for visitors that will consistently lead back to the proper video and playlist in your player.