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:
- playing
- paused
- stopped
- 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:
- "none" - No connectivity at present
- "mobile" - Cellular network connectivity (it is not possible to differentiate between 2G/3G/4G)
- "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
- "playing"
- "buffering" - stream is buffering
- "paused" - Catch-up items paused by the user
- "stopped" - Live streams stopped by the user
- "complete" - for catch-up items that have finished
- "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:
- "none" - No connectivity at present
- "3g" - 3G Network connectivity
- "wifi" - Wi-Fi connectivity
- "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?!);
}
}
});