Y!Live - Webservice APIs

REST

Using the REST API, we will grab a collection of random streams that we can display on our page.

Javascript and Flash Embedding

Once we embed our Flash file into the page, we can interact with it via the Javascript API which is documented here.

Creating the sample

Add your fallback content to the page

Looking at the source of our sample page, you will see four HTML elements which have fallback, or alternative content. This is content that will be replaced by our Flash files. You can assume that users who see the alternative content do not have Flash and/or Javascript installed. For example:

<div id="spot1">Alt content 1</div>
<div id="spot2">Alt content 2</div>
<div id="spot3">Alt content 3</div>
<div id="spot4">Alt content 4</div>

In a real-world scenario you would want to provide relevant content to your users such as static images, or links to download the latest Flash player and instructions on enabling Javascript

Query REST API

We use PHP and curl to gather data about broadcasts using the Yahoo! Live REST API. We are using the following querystring parameters:

sort Set to random, the broadcasts returned from the server will be randomly sorted.
format Set to json, since we are going to store the result of this query as a Javascript variable.
count Set to 50, which means to return a max of 50 results. If there are less than 50 active broadcasts, the actual count will be less than 50.

<?php
// initialize curl handle
$ch = curl_init();

// URL for REST API with parameters
curl_setopt($ch, CURLOPT_URL, 'http://live.yahoo.com/api/v1/broadcasts?sort=random&format=json&count=50'); 

// return into a variable
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); 

// times out after 10 sec
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

// store the result of our query to a PHP variable
$result = curl_exec($ch); 

// check for error
if (curl_errno($ch)) {
	echo "curl error: " . curl_errno($ch) . ' ' . curl_error($ch);
}

// close handle
curl_close($ch);
?>
<script type="text/javascript">
/* -------------------------------------------------------------------------------- */
/* Javascript variables                                                             */
/* -------------------------------------------------------------------------------- */
var result = <?php echo $result; ?>;
var players = ['spot1', 'spot2', 'spot3', 'spot4'];
var playing = [];
</script>

For more information on REST and PHP, click here.

Embed Flash content

As discussed here, we prefer SWFObject 2 to embed our Flash into our pages. It provides an easy way to perform version checking for the Flash Player, as well as offer the alternative content fallback we created above.

<script type="text/javascript" src="/path/to/swfobject.js"></script>

The Flash movie we want to embed can be found at http://live.yahoo.com/swf/v1/ylsp/<permalink>, where <permalink> refers to a user's Channel ID. This is the information we will be using from the REST result which we now have in a Javascript variable called result.

/* -------------------------------------------------------------------------------- */
/* function addPlayers() This function will launch on page load, to embed the Flash */
/* movies into the page. It also sets up event handlers for user clicks and adds    */
/* channel information next to each player.                                         */
/* -------------------------------------------------------------------------------- */
function addPlayers() {
    if(!result.broadcasts) return;
    for(var i=0; i<result.broadcasts.length; i++) {
        if(i == players.length) break;
        if(document.getElementById(players[i])) {
            
            // store a reference to a specific channel from the result
            var channel = result.broadcasts[i].channel;
            var playerParent = document.getElementById(players[i]).parentNode;
            
            // embed the swf with info from the channel
            swfobject.embedSWF('http://live.yahoo.com/swf/v1/ylsp/' + channel.id, players[i], '400', '300', '9.0.47', '/path/to/swf/expressInstall.swf', {}, {}, { id:'mySwf' + (i+1), name:'mySwf' + (i+1), styleclass:'myswf' });
            
            // add controls container
            var controls = document.createElement('div');
            controls.className = 'controls';
            playerParent.appendChild(controls);
            
            // add a button to view each channel
            var btn = document.createElement('img');
            btn.setAttribute('width', '196');
            btn.setAttribute('height', '26');
            btn.className = 'btn';
            btn.setAttribute('src', '/path/to/button.gif');
            btn.onclick = function() { window.location.assign('http://live.yahoo.com/' + channel.id); };
            controls.appendChild(btn);
            
            //add channel permalink
            var pl = document.createElement('span');
            var plText = document.createTextNode(channel.id);
            pl.appendChild(plText);
            controls.appendChild(pl);
        }
    }
    playing = result.broadcasts.splice(0, players.length);
}

Note that you will need to provide the correct path to expressInstall.swf located on your server. Also, Flash 9.0.47 is our minimum required version of Flash for use with Yahoo! Live. If you are using an alternative embedding method, make sure you can enforce a minimum version of 9.0.47.

Using setPermalink()

The following is a Javascript function that will randomize the broadcasts by calling setPermalink() on the embedded Flash movie. We also incorporate the use of Yahoo User Interface components to allow easier interaction with the Dom as well as Event handling. You can read more about YUI here.

/* -------------------------------------------------------------------------------- */
/*  function randomize() This function is called when we click the Randomize button */
/* -------------------------------------------------------------------------------- */

function randomize() {
    if(!result.broadcasts) return;

    var controls = YAHOO.util.Dom.getElementsByClassName('controls', 'div', 'players');
    var swfs = YAHOO.util.Dom.getElementsByClassName('myswf', 'object', 'players');
    var up_next = [];

    result.broadcasts = result.broadcasts.concat(playing);
    up_next = result.broadcasts.splice(0, swfs.length);

    for (var i=0, len=up_next.length; i<len; i++) {
        (function(control, swf, channel) {
            control.getElementsByTagName('img')[0].onclick = function() { window.location.assign('http://live.yahoo.com/' + channel.id); };
            control.getElementsByTagName('span')[0].innerHTML = channel.id;
            swf.setPermalink(channel.id);
        })(controls[i], swfs[i], up_next[i].channel);
    }
    playing = up_next;
}
YAHOO.util.Event.onDOMReady(addPlayers);

View working sample

Conclusion

This example demonstrates how to use the Javascript and REST APIs to create custom Yahoo! Live applications. Refer to the Yahoo! Live API documentation for the entire list of functions and their descriptions.