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.