If you're using Joost Links in a widget you often need to know if they can be played by the user of your widget. It's a fact of life (and of business) that certain videos are only playable in some regions; and from time to time, a channel line-up may change.

To check that a Joost Link is playable, you can use retrieveURL in the Engine class. Here's a very simple example of how you might check a given URL:

var url="http://joost.com/123456a";

Engine.retrieveURL(url, testChannelListener);

var testChannelListener = {

    updateSuccess : function(channel, entry) {
        logMessage("updateSuccess() "+channel.title+" "+entry.title);
    },

    updateFailure : function(errorCode) {
        if(errorCode=="load:404"){
        logMessage("Cannot be played because not a Joost link");
        }else
        if(errorCode=="load:403"){
        logMessage("Cannot be played because of geo restrictions);
        }else{
        logMessage("Cannot be played for some reason "+errorCode);
        }
    }
    
}

Let's walk though it:

First, get your URL and send it to retrieveURL

var url="http://joost.com/123456a";

Engine.retrieveURL(url, testChannelListener);

Engine.retrieveURL takes two arguments, the URL you want to check and a listener callback which is called when retrieveURL has the information about the URL.

I find callbacks rather strange, as from what I can remember of my Java days I never used anything like them - but here we can just think of them as functions to be called when something that takes time has been completed, in this case the lookup about the URL, (the downside about callbacks is that it's a bit complicated to send arguments to them, but never mind that here as we don't need to).

Second, write a listener

The second argument is our class, testChannelListener. What we want to happen here is for this class to listen for two possible function calls which the Joost engine might provide depending on what it finds for the URL.

updateSuccess

If it is a Joost Link and we can play it we get a success. Here we just print to the console (see output to the console by calling it up using control-shift-D)

    updateSuccess : function(channel, entry) {
        logMessage("updateSuccess() "+channel.title+" "+entry.title);
    },

If we get this we can use the channel and the entry and the various methods associated with those.

updateFailure

If there's a problem we usually get a failure:

    updateFailure : function(errorCode) {
        if(errorCode=="load:404"){
        logMessage("Cannot be played because not a Joost link");
        }else
        if(errorCode=="load:403"){
        logMessage("Cannot be played because of geo restrictions);
        }else{
        logMessage("Cannot be played for some reason "+errorCode);
        }
    }

and an errorCode is returned.

This functionality is very useful for bookmarks or the retrieval of other Joost content that you might want to suggest to the user, for example with the URL methods. I use it for making suggestions to the user.

The detail of this part of the Joost Widget API is in the Engine section - see retrieveURL.