Making Media API Calls with Dynamic Script Tags

Product
Video Cloud
Applies to Roles
Developer
Version
Brightcove 5
Modules
Media API
Edition
All
Created by Grant Goodman.

Browser security rules are an obstacle that can prevent you from communicating with the Media API from JavaScript. One solution is to use a server-side proxy, which has the advantages of allowing unfettered communication and also keeping your token secure (since it no longer needs to live in your JavaScript code). Another convenient option, however, is dynamic script tags.

The src attribute of the script tag is not domain-checked by browsers. That means you can set the src to be a URL on another server, and effectively permit cross-domain communication. However, what comes back from the server when the src is requested must be valid JavaScript. Fortunately many services, including the Video Cloud Media API, allow you to specify a "callback" parameter. When you do this, the JSON response is wrapped in a function call, with the name of the function being the value of the callback parameter. For example:

// Make a request like this:
http://api.brightcove.com/services/library?callback=response
 
// and the response will be returned as:
response(... json data ...);
//
// which will automatically invoke a function "response" which you have 
// defined in your code

Click here to see this in action.

Dynamic script tags are not without their flaws though. There are security concerns: because the script tag is part of your document, your document can be traversed by a malicious script at the location of the src attribute. Of course, only the Media API will exist at our api.brightcove.com URL. If you're still uncomfortable with this, why not try another approach, like the server-side proxy.

For this example, we're using Jason Levitt's JSONScriptRequest class, published on XML.com, to help us dynamically create and insert our script tag.

Create the callback function

First we'll create the callback function that will handle the results. The function will need to iterate through the object to generate a list of video names to display. After that, we'll create a new JSONScriptRequest instance to manage the script tag for us. Insert the following code into the <head> of your web page:

<script type="text/javascript">
 
  // Define the callback function
  function response(jsonData) {
		var resp = document.getElementById("resp");
		for (var i=0; i<jsonData["items"].length; i++) {			
			resp.innerHTML += jsonData["items"][i].name;
			resp.innerHTML += "<br/>";
		}
	}
	
	
	// The web service call
	//
	var req = "http://api.brightcove.com/services/library?"
	req += "command=find_all_videos
    &token=PILqAlQCtq0AyAEYsBgfOSshsB3kVU%2F%2FWD%2BSGSVbPWE%3D&video_fields=id,name,referenceId"
	req += "&callback=response";
	
	// Create a new request object
	bObj = new JSONscriptRequest(req); 
	// Build the dynamic script tag
	bObj.buildScriptTag(); 
	// Add the script tag to the page
	bObj.addScriptTag();
</script>

Substitute your own token to search your own account. Remember, your token needs to be URL-encoded! See Getting Started with the Media API for more info.

Note that the callback parameter does not accept certain characters. The following characters are escaped before the response document is returned:

' " < > & % ; ( ) +

For example, callback=cb(0) will be converted to cb\x280\x29.

Certain applications may need to execute a function or other code at the point the callback event is received to determine the function that serves as the actual callback target. Wrap this code in a uniquely named function and provide that function name as the callback parameter:

// timestamp from epoch in milliseconds.
var ts = new Date().getTime();
// create a uniquely named function
var fn = "callback"+ts;
window[fn] = function(data) { cb(0)(data); }

Alternatively, execute your code before calling the Read API:

// timestamp from epoch in milliseconds.
var ts = new Date().getTime();
// create a uniquely named variable with the result of your computation.
var fn = "callback"+ts;
// assumes that cb(0) returns a function.
window[fn] = cb(0);

In either case, the safely-named "callbackTIMESTAMP" callback can be used as a value to the Read API callback parameter.

Displaying the response

In the <body> we'll create a <div> within which to output the list of videos:

<h3>Videos</h3>
<div id="resp"></div>

Preview this in any browser and you'll see a dynamically generated list of videos from your account.