To get you started working with the Viggle VApp Javascript API we’ve put together this walk through of the functions you’re likely to want to use right away and to give you a feel for how the rest should be invoked. We’ll be building a VApp which checks to see if the user is checked into the show through whose show page they’ve accessed your app. If they are checked in, we’ll show them reviews of the show from some popular review sites and if they aren’t we’ll prompt them to go and check in first.
Initializing the VApp Javascript Bridge
To get started working with the VApp API your html5 application needs to establish contact with the Viggle app. This is done through a javascript bridge, like so:
document.addEventListener('VAPPReady', onBridgeIsReady, true);
This is just a standard call to the Javascript event listener binding the onBridgeIsReady function to the message ‘VAPPReady’. You’ll want to put all the logic of your interaction with Viggle inside of this function. Assuming you’re using jQuery, you can do it like this:
(function() {
function onBridgeIsReady() {
//Your VApp logic goes here
}
// Kick off script
document.addEventListener('VAPPReady', onBridgeIsReady, true);
})();
A nice benefit of injecting the Javascript bridge in this way is that you can run your app outside of Viggle and it will function exception free, waiting for the event to fire before executing the Viggle exclusive content.
Setting the title bar
Next up, we want set the title of the page, it’s easy with this call:
VAPP.setTitleBarTitle(function(message) {}, 'Reviews');
This sets the title of the chrome hosting your VApp to ‘Reviews’. Note that all Vapp functions are methods of the VAPP object and similarly invoked. The function(message){} parameter is the callback function you would like to have executed when the title bar has been set. In the case of this method, the message simply contains diagnostic information.
Getting show information
The core of the app happens once we’ve retrieved the current show page’s show information, like this:
VAPP.getCurrentShow(function (message) { …
Now in the case of this function we are interested in the data it returns, so let’s parse the message into a json object so we can use it:
var showInfo = JSON.parse(message);
Now we do some error checking and make sure the show info call succeeded. If it failed we want to send the user a message, to that effect, in a Viggle modal popup .
//every VAPP callback returns a status in the callback message,
//we check here that it's succeeded
if (showInfo.status !== 'success') {
VAPP.showModal(function(message) {}, 'Oops ...', 0, 'Unable to get show info.');
return;
}
Ok. Now that we know we have the data we want, we can grab the show’s name from the json object we instantiated above and set the subtitle of the chrome:
// Name of the current show
var showName = showInfo.data.program_data.program_title;
// Display the show name in the sub header bar
VAPP.setTitleBarSubTitle(function(message) {}, showName);
Is the user checked into the current show
Next we need to see if the user’s checked into the show, if they aren’t we’ll send them back to the show page and tell them to check in.
//Check if user is checked in
VAPP.getCurrentShowCheckInOffset(function(message){
//Parse the JSON message that is returned
var checkInInfo = JSON.parse(message);
//check to see if the offset is greater than 0,
//if it isn't we know that the user hash't checked into the show
if (!checkInInfo.data.offset > 0) {
//we tell them that they need to check in
VAPP.showModal(function(message) {}, 'Oops ...', null, 'You are not checked '
+ 'into this show', 'Check in and then try again', false);
//and close the VApp, bringing them back to the show page
VAPP.close(function(m){});
return;
}
…
Completing the App
Now that we have verified that the user is checked into the current show, we can display the links to the pertinent review sites:
//we url encode the show name so that it can used as part of the URL
var showNameEncoded = showName.replace(/ /g, '-').toLowerCase();
//build the dictionary of sites and urls to the current show's reviews
var urlList = {
'Metacritic' : 'http://www.metacritic.com/tv/' + showNameEncoded,
'TV' : 'http://www.tv.com/shows/' + showNameEncoded,
'MSN' : 'http://tv.msn.com/tv/series/' + showNameEncoded,
'Jinni' : 'http://jinni.com/tv/' + showNameEncoded
};
//and write them out to a list
for (url in urlList) {
$('#reviews-list').append('<li><a href="' + urlList[url]
+ '">' + url + '</a></li>');
};
You can find the complete VApp at the url below. To see it in action plug it into your developer bar in your Viggle App. Open it in a conventional browser and view source to grab the code.
http://assets.viggleassets.com/assets/a/c/f/2/acf23c4d7ce2ff3b6203ade2b3d9fa23.html
Should you need any help while developing your VApp, ask a question in our developer forum. It is monitored by Viggle Engineers and they will help you out if the community doesn’t beat us to it.