Version 1.0.1 | Implementation guidelines

The Radioplayer mobile Station Screen API allows radio stations to interact with the Radioplayer mobile app using JavaScript in their web-pages.

Every station is able to develop their own Station Screen, which is shown on the mobile app's "Now playing" screen when the station is played.

In order to interact with the app, station developers must link to the Radioplayer JavaScript bridge file, like this:

 
 

This can go at the bottom of the page, as long as it's above the code you use to call it.

All API calls send and receive JavaScript Objects. To make a call to the API in the simplest of terms, it needs to be sent as an object to the sendToDevice method, like this:

 // pause the stream
 RPBridge.sendToDevice({
            call: 'pause'        
        });

If you are requesting data from the app, you must also provide a callback function in which to manipulate the received data, like this:

 // check battery level, and squawk if less than 15%
 RPBridge.sendToDevice({
            call: 'battery_level',
            success: function (result) {

                if(result.value < 0.15) {
                    alert("Oh no, you only have " + Math.round(result.value*100) + "% of your battery left!");
                }
            },
            error: function(message) {
                alert("Check of the battery level failed! " + message);
            }
        });

The response received from the app is a JavaScript object passed as an argument to the callback function. You can add an optional "error" callback function too, to catch errors. This always returns a single error string. All calls to the API are done through the "sendToDevice" method. The object passed into this method requires a "call" parameter, details of which can be seen in the list of calls below. Some of the methods require further parameters, also described and shown in the call descriptions below.


Receiving events from the app

The API also allows developers to add an event handler function for receiving events from the device. This is done like so:

    // set up an event listener to the device, to handle events sent back
    RPBridge.registerEventCallback(function (event_object) {
            alert("App has sent us an event: " + event_object.event_type);
    });

The available events sent to the Bridge from the device are listed in the section "Device Events", below.


Getting data from the app

The following calls can be made to the application to get information from it.


Current station information

Provides the Station Screen with information about the currently playing station. Information includes:

  • The Station ID
  • URL to one or more station logos
  • Station name
  • Description
  • Gradient colours
  • Default stream URL, type and quality (which may be different from the stream currently playing)

Call: station_info

Arguments: none. The native app will send data for the currently playing station. If the app is currently playing catch-up content, the data will be sent for the parent radio station of the catch-up.

Returns: Returns JSON representing the radioplayer API information for a station. The object is arranged like this:

    "services":
        [
            {"id":"310",
             "name":"BBC Radio Gloucestershire",
             "description":"The latest news and the best music.",
             "categories":
                ["Pop / Chart",
                 "Rock / Indie",
                 "Jazz  / Blues / R&B",
                 "Classical / World Music",
                 "News / Sport / Talk"
                ],
              "links":
                [
                    {"url":"http://news.bbc.co.uk/local/gloucestershire/hi/",
                     "mimeValue":"text/html",
                     "language":"en",
                     "description":"BBC Radio Gloucestershire Homepage"
                     }
                ],
              "multimedia":
                [
                    {"url":"http://www.bbc.co.uk/iplayer/images/radioplayer/86x48/bbc_radio_gloucestershire.png",
                     "mimeValue":"image/png",
                     "language":"en",
                     "width":86,
                     "height":48}
                ],
             "liveStreams":
                [
                    {"player":"http://www.bbc.co.uk/iplayer/console/bbc_radio_gloucestershire",
                     "streamRestriction":
                        {"value":"UK",
                         "relationship":"allow"
                        },
                     "audioStreams":
                        [
                            {"streamSource":
                                {"url":"http://icecast.commedia.org.uk:8000/soundart.mp3",
                                 "mimeValue":"audio/mpeg"},
                                 "audioFormat":"urn:mpeg:mpeg7:cs:AudioPresentationCS:2001:3",
                                 "bitrate":
                                    {"target":128000,
                                     "variable":false},
                                 "streamRestriction":
                                    {"value":"UK",
                                     "relationship":"allow"}
                                    },
                                 {"streamSource":
                                    {"url":"http://icecast.commedia.org.uk:8000/soundart.mp3",
                                     "mimeValue":"audio/mpeg"
                                    },
                                    "audioFormat":"urn:mpeg:mpeg7:cs:AudioPresentationCS:2001:3",
                                    "bitrate":
                                        {"target":64000,
                                         "variable":true
                                        },
                                    "streamRestriction":
                                        {"value":"UK",
                                         "relationship":
                                         "allow"
                                        }
                                  }
                         ]
                    }
                 ],
                 "epgLanguages":[],
                 "socialIds":
                    [
                        {"type":"facebook",
                         "uid":"fb123abc"
                        },
                        {"type":"twitter",
                         "uid":"twitter123abc"
                        }
                    ],
                 "groupName":"BBC Radio Gloucs"
              }
           ]

Example:

 RPBridge.sendToDevice({
            call: 'station_info',
            success: function (result) {

                // set the SRC of a station logo to the returned image URL
                if(result.services.length > 0) {
                    if(result.services[0].multimedia.length > 0) {
                        $('#stationlogo').src(result.services[0].multimedia[0].url);
                    }
                }

            },
            error: function(message) {

                // hide the station logo image (we can't get the URL)
                $('#stationlogo').hide();
            }
        });

Play state

Returns information about whether the stream is currently paused, playing or finished

Call: play_state

Arguments: none

Returns: String value representing the play state. Possible returned values (all lower-case) are:

  1. playing
  2. paused
  3. stopped
  4. finished

Example:

 RPBridge.sendToDevice({
            call: 'play_state',
            success: function (result) {
                if(result.value === "stopped") {
                    alert("What's up?");
                }
            }
        });

Most recent metadata

Provides a copy of the most recent meta-data received by the app in the station stream, if available.

Call: meta_data

Arguments: none

Returns: The most recent broadcast stream metadata that the app has for this station, as a Javascript Object. Note that this will depend on what individual stations provide. An example of the data for a live stream is as follows:

	
	{
	    "meta_data_type":"live",
	    "meta_data":  
	    {
	        "StreamTitle":"Elbow - One day like this",
	        "StreamUrl":"http://www.bbc.co.uk",
	    }
	}
	

For on-demand content, the "meta_data_type" would be "ondemand", and the data would look something like this:

	
	{
 		"meta_data_type":"ondemand",
		"meta_data":
		{
			"id":"odp:/crid://absoluteradio.co.uk/podcasts/60877",
			"links":[],"multimedia":[
				{
					"mimeValue":"image/jpg",
					"language":"en",
					"width":86,
					"height":48
				}
			],
			"categories":[],
			"recommendation":false,
			"locations":[],
			"onDemandStreams":[
				{
					"player":"http://player.absoluteradio.co.uk/core/radioplayer/podcasts/The-Annabel-Portcast/60877/",
					"streamRestriction":{
						"value":"",
						"relationship":"allow"
					},
					"audioStreams":[
						{
							"streamSource":
								{
									"url":"http://podcast.as34763.net/lloydcut/20120821201719.mp3",
									"mimeValue":"audio/mp3"
								},
							"audioFormat":"urn:mpeg:mpeg7:cs:AudioPresentationCS:2001:3",
							"bitRate":
								{
									"target":64000,
									"variable":false
								}
						}
					],
					"availableStart":"2012-08-21T19:17:19Z",
					"availableStop":"2020-01-01T00:00:00Z"
				}
			],
			"programmeEvents":[],
			"socialIds":[],
			"odRpIds":["100"],
			"name":"The Annabel Portcast",
			"description":"The AnnabelPortcast- 21st August. When we have an extra bank holiday, then whatever they decide to call it, we'll all know it as Annabel's day, because she's ma"
		}
	}
		

This data is a copy of the data sent by the event "meta_data_update", documented in the device events section below.

Station listening information

Provides a list of metrics about listening on this station. The metrics include:

  • Number of minutes this station has been played in total
  • Number of minutes this station has been played in this session
  • Whether this station is set as a favourite in the app
  • Number of sessions for this station since install
  • Time elapsed since the last listen to this station
  • Whether this station or its content has been shared by the app
  • Number of catch-up items from this station started
  • Total number of catch-up minutes listened to from this station

Call: listening_info

Arguments: none

Returns: A JSON object with the following structure

   {
    "total_minutes" : 10,               // rounded total number of live minutes listened to on this app
    "session_minutes" : 5,              // rounded number of minutes listened to on this app this session
    "session_count" : 2,                // how many times has this station been listened to (including now)
    "catchup_minutes" : 0,              // how many mins of catchup material from this station
    "catchup_items" : 0,                // how many different catchup items listened to
    "last_listen_minutes" : 4434,       // how long has it been since this station was last listened to (until this session)
    "favourite" : false,                // has the user added this station to their favourites
    "shared" : false                    // has the user shared this station
   }

Note that "last_listen_minutes" is set to -1 if this is the first session

Example:

 RPBridge.sendToDevice({
            call: 'listening_info',
            success: function (result) {

                // store the session count in a variable
                var num_sessions = result.session_count;

                alert("You have listened to this station " + num_sessions + " times so far.");
            },
            error: function(message) {
                alert("Can't get the station listening info! " + message);
            }
        });

Device location

Provides location details for this device, if permitted and available.

Call: device_location

Arguments: none

Returns: A latitude and longitude geographic coordinate pair. It will return a message in the error callback if the device does not support or the user does not allow location services.

Example:

 RPBridge.sendToDevice({
            call: 'device_location',
            success: function (result) {

                // lat and long are both geographic coordinates like: -122.083739
                var lat = result.latitude;
                var lng = result.longitude;

                alert("You are at: " + lat + " lat, " + lng + " long.");
            },
            error: function(message) {
                alert("Cannot determine device location: " + message);
            }
        });

Specific Operation System version

Tells the Station Screen the specific operating system version number running on the device. Useful for determining capabilities

Call: os_version

Arguments: none

Returns: A version number string in the "value" of the resulting object e.g. "5.0.1"

Example:

 RPBridge.sendToDevice({
            call: 'os_version',
            success: function (result) {
                alert("This OS version is " + result.value);
            }
        });

Connectivity

Reports whether the device is connected via Wi-Fi or 3G connection

Call: connectivity

Arguments: none

Returns: A lower-case string in the "value" of the returned object describing the current connectivity of the device. The string can be one of the following options:

  1. "none" - No connectivity at present
  2. "mobile" - Cellular network connectivity (it is not possible to differentiate between 2G/3G/4G)
  3. "wifi" - Wi-Fi connectivity

Example:

 RPBridge.sendToDevice({
            call: 'connectivity',
            success: function (result) {

                if(result.value === "wifi") {
                    alert("You currently have a wi-fi connection!");
                }

            }
        });

Volume level

Returns the current stream volume level set on the device. Note, this is the level of the radioplayer stream, not necessarily the ringer or other stream volumes.

Call: volume

Arguments: none

Returns: A floating point number between 0 and 1, based on the min and max available volumes of the device.

Example:

 RPBridge.sendToDevice({
            call: 'volume',
            success: function (result) {

                if(result.value > 0.5) {
                    alert("Volume is more than halfway!");
                }

            }
        });

Battery level

Reports the level of the battery of the device

Call: battery_level

Arguments: none

Returns: A floating point number between 0 an 1 representing the current battery level of the device (with 1 being full)

Example:

 // check battery level, and squawk if less than 15%
 RPBridge.sendToDevice({
            call: 'battery_level',
            success: function (result) {

                if(result.value < 0.15) {
                    alert("Oh no, you only have " + Math.round(result.value*100) + "% of your battery left!");
                }
            },
            error: function(message) {
                alert("Check of the battery level failed! " + message);
            }
        });

Unique ID

When installed the app registers a 32 hexidecimal digit (128 bit) Globally Unique Identifier (guid). It is unique per installation of the Radioplayer app, and is persistent as long as the app is installed on that particular device. You can use this id to identify a unique user, albeit entirely anonymously. A common use for the guid is to provide log-in or other "remembered" services for a particular user.

Call: get_guid

Arguments: none

Returns: A 32 character string (no hyphens) representing the guid for this application on this device is stored in the "value" value of the result object

Example:

 RPBridge.sendToDevice({
            call: 'get_guid',
            success: function (result) {
                alert("My unique ID is: " + result.value);
            }
        });

App version

Describes the version of the Radioplayer native app. Useful for determining changes to this API

Call: app_version

Arguments: none

Returns: A string representation of the version number of the radioplayer app e.g. 1.3.2

Example:

 RPBridge.sendToDevice({
            call: 'app_version',
            success: function (result) {
                    alert("This is version " + result.value + " of the Radioplayer mobile app");
            }
        });

Affecting the app

Pause

Pauses the current stream, if it is playing

Call: pause

Arguments: none

Returns: nothing

Example:

 RPBridge.sendToDevice({
            call: 'pause',
            error: function(message) {
                alert("Pause request failed: " + message);
            }
        });

Play

Plays the current stream, if it is paused or stopped

Call: play

Arguments: none

Returns: to be defined

Example:

 RPBridge.sendToDevice({
            call: 'play',
            error: function(message) {
                alert("Play request failed: " + message);
            }
        });

Change stream

Requests that the app change the stream to a different one. This stream will begin to play, if successful. NOTE we may want to restrict streams to the same domain as the default stream from this station

Call: change_stream

Arguments: A Stream URL as the "url" value in a key/value pair.

Returns: nothing. Will call the "error" call-back if unsuccessful

Example:

 RPBridge.sendToDevice({
            call: 'change_stream',
            url: 'http://icecast.commedia.org.uk:8000/soundart.mp3',
            error: function(message) {
                alert("Stream change request failed: " + message);
            }
        });

Change Station

Switches the Radioplayer current station to another station within this station's parent group. This call goes further than just changing the stream. When called this acts as though the user has changed station through the user interface. The stream will change, the new station will be added to presets if not already there, and the pull-down will be refreshed with the new station's information.

Call: change_station

Arguments: A station ID as the "id" value in a key/value pair.

Returns: nothing. Note an error will be thrown if the id passed in does not represent a station within the same parent group as the currently playing station.

Example:

 RPBridge.sendToDevice({
            call: 'change_station',
			id: 808,					// the radioplayer id of the station to change to
            error: function(message) {
                alert("Could not change to Total FM: " + message);
            }
        });

Device Events

The following events can be captured by developers by using the "registerEventCallback" method of the API (documented above).

The parameter passed in to the event handler function is a Javascript object with at least one attribute: "event_type". For some events this object will also include a "value" attribute.

Application has moved to the foreground

This is called shortly after the application has been moved to the foreground, after a period in the background.

event_type: app_foreground

Additional attributes: none

Application moving to the background

Called when the application moves into the background (for example when switching to another app, when the Home button is pressed, or when an incoming call is accepted). NB. This event is under review at present.

event_type: app_background

Additional attributes: none

Volume change

Called when the stream volume is changed on the device by the user. Includes a number between 0 (min) and 1 (max) in the "value" parameter.

event_type: volume_change

Additional attributes: "value" - float between 0 and 1, (e.g. 0.3)

Example:

    // set up an event listener to the device, to handle events sent back
    RPBridge.registerEventCallback(function (event_object) {

            // deal with volume changes
            if(event_object.event_type === "volume_change") {
                var volume = parseFloat(event_object.value);
                alert("The user's just changed the volume. It's now: " + volume);
            }
    });

Change of Play-state

Called when the current stream is paused or stopped

event_type: play_state_change

Additional attributes: "state": A string containing one of the following states

  1. "playing"
  2. "buffering" - stream is buffering
  3. "paused" - Catch-up items paused by the user
  4. "stopped" - Live streams stopped by the user
  5. "complete" - for catch-up items that have finished
  6. "error" - stream error (e.g. not found)

Meta-data update event

Called when the stream metadata is updated, as the stream is being played. A typical use-case here would be to keep an up-to-date "Now Playing" display on the Station Screen.

event_type: meta_data_change

Additional attributes: "data": A JavaScript object representing the new available meta-data. Note that the format of this object will differ from station to station. Please examine example data from your station to determine how best to use this information. An example of the meta-data returned is shown below:

	{
	    "event_type":"meta_data_change",
	    "meta_data_type":"live",
	    "meta_data":  
	    {
	        "StreamTitle":"Elbow - One day like this",
	        "StreamUrl":"http://www.bbc.co.uk",
	    }
	}
	

Connectivity change

Called when the connectivity state of the device changes.

event_type: connectivity_change

Additional attributes: "state", an all-lowercase string containing one of the following items:

  1. "none" - No connectivity at present
  2. "3g" - 3G Network connectivity
  3. "wifi" - Wi-Fi connectivity
  4. "4g" - 4G Network connectivity

Example:

    // set up an event listener to the device, to handle events sent back
    RPBridge.registerEventCallback(function (event_object) {

            // squawk if connectivity is lost
            if(event_object.event_type === "connectivity_change") {
                
                if(event_object.state === "none") {
                    alert("Are you in a tunnel or something?!);
                } 

            }
    });