Technische Dokumentation: Station Screen JS API
Die mobile Radioplayer Sender-Screen API erlaubt Radiosendern mit der mobilen Radioplayer-App unter der Verwendung von JavaScript in deren Websites zu interagieren.
Jeder Sender kann seinen eigenen Sender-Screen entwickeln, welcher dann in der mobilen App am „Now Playing“ Screen anzeigt, welcher Sender aktuell gespielt wird.
Um mit der App interagieren zu können, müssen die Entwickler der Sender zum Radioplayer JavaScript bridge File verlinken:
<script type="text/javascript" src="http://static.radioplayer.de/mobile/v2/stationview/js/rp.webview.api.min.js">
</script>
Dies kann auch weiter unten auf der Seite erfolgen, allerdings muss es sich oberhalb des Aufrufs der Funktion befinden.
Alle API-Aufrufe senden und empfangen JavaScript Objekte. Um eine einfache Anfrage an die API zu machen, muss dies als ein Objekt an die sendToDevice Methode gesendet werden:
RPBridge.sendToDevice({
call: 'pause'
});
Wenn Sie Daten von der App anfordern, benötigen Sie auch eine callback-Funktion, in welcher die erhaltenen Daten gehandhabt werden:
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);
}
});
Die Antwort, die Sie von der App erhalten ist ein JavaScript Objekt, welches an die callback-Funktion geliefert wird. Sie können optional eine „error“ callback-Funktion implementieren, die sämtliche Errors auffängt. Vorteil ist hierbei, dass immer ein einziger Error-String ausgegeben wird. Alle Aufrufe der API passieren immer durch die „sendToDevice“ Methode. Die Objekte, die in dieser Methode verwendet werden, benötigen alle einen „call“-Parameter. Eine detaillierte Liste dieser Parameter finden Sie weiter unterhalb. Einige Methoden benötigen noch weitere Parameter, die ebenfalls weiter unten beschrieben sind.
Erhaltene Events von der App
Die API erlaubt Entwicklern eine Event-Handler-Funktion zum Erhalten von Events von den Geräten hinzuzufügen. Dies passiert wie folgt:
RPBridge.registerEventCallback(function (event_object) {
alert("App has sent us an event: " + event_object.event_type);
});
Die verfügbaren Events, die Sie vom Geräte zur Bridge senden können finden weiter unten im Bereich „Device Events„.
Daten von der App erhalten
Um Informationen zu erhalten, können die folgenden Aufrufe an die App gesendet werden.
Aktuelle Senderinformation
Stellt den Sender-Screen mit Informationen über den aktuell gespielten Sender zur Verfügung. Die Informationen beinhalten:
- Sender ID
- URL zu einem oder mehreren Sender-Logos
- Sendername
- Beschreibung
- Farbverlauf
- Default Sender URL, Typ und Qualität (dies kann sich vom aktuell gespielten sender unterscheiden)
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:
[
{"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"
}
]
Beispiel:
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();
}
});
Spielstatus
Gibt Informationen aus, ob der aktuelle Stream gespielt, auf Pause oder beendet ist.
Call: play_state
Arguments: none
Returns: String-Wert repräsentiert den Play Status. Mögliche Werte (in Kleinbuchstaben) sind:
- playing
- paused
- stopped
- finished
Beispiel:
call: 'play_state',
success: function (result) {
if(result.value === "stopped") {
alert("What's up?");
}
}
});
Neuesten Metadaten
Dies bietet, wenn verfügbar, eine Kopie der neuesten Metadaten, die die App im Sender-Stream erhält.
Call: meta_data
Arguments: none
Returns: Die neuesten Broadcast-Stream Metadaten, welche die App für diesen Sender hat, als JavaScript Objekt.
Note Dies ist abhängig davon, was die einzelnen Sender zur Verfügung stellen. Ein Beispiel für die Daten eines Livestreams folgt:
"meta_data_type":"live",
"meta_data":
{
"StreamTitle":"Elbow - One day like this",
"StreamUrl":"http://www.bbc.co.uk",
}
}
Für On-Demand Inhalte ist „meta_data_type“ auf „ondemand“ gesetzt und sieht wie folgt aus:
"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"
}
}
Diese Daten sind eine Kopie derjenigen, die von dem Event „meta_data_update“ gesendet werden. Eine Dokumentation dazu finden Sie im Bereich device section unterhalb.
Station listening information
Bietet eine Liste an Metriken über das Hören dieses Senders. Diese beinhalten:
- Anzahl an Minuten, die dieser Sender insgesamt gespielt wurde
- Anzahl an Minuten, die dieser Sender in einer Session gespielt wurde
- Ob dieser Sender als Favorit in der App gespeichert ist
- Anzahl der Sessions dieses Senders seit Installation der App
- Vergangene Zeit seit dem letzten Hören dieses Senders
- Ob der Sender selbst oder Inhalte von der App geteilt wurden
- Anzahl an Catch-up Items vom gestarteten Sender
- Gesamtanzahl of Catch-up Minuten die von diesem Sender gehört wurden
Call: listening_info
Arguments: none
Returns: Ein JSON Objekt mit folgender Struktur:
"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
}
Anmerkung: „last_listen_minutes“ ist auf -1 gesetzt, sofern dies die erste Session ist.
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);
}
});
Lokalisation des Geräts
Bietet Details zum Ort des Geräts, sofern diese erlaubt und verfügbar sind.
Call: device_location
Arguments: none
Returns: Breiten- und Längengrade der geografischen Daten werden als Paar geliefert. Es wird eine Nachricht im Error Callback zurückgegeben, wenn das Gerät diese Information nicht unterstützt oder der User diese Information nicht preisgeben will.
Beispiel:
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);
}
});
Spezifische Version des Betriebssystems
Sagt dem Sender-Screen die spezifischen Version des Betriebssystems, die aktuell am Gerät installiert ist. Dies ist vor allem für das bestimmen der Fähigkeiten relevant.
Call: os_version
Arguments: none
Returns: Eine Versionsnummer als String im „value“ des erhaltenen Objekts; z.B.: „5.0.1“
Beispiel:
call: 'os_version',
success: function (result) {
alert("This OS version is " + result.value);
}
});
Verbindung
Berichtet, ob das Gerät via WLAN oder 3G Verbindung verbunden ist.
Call: connectivity
Arguments: none
Returns: Ein String in Kleinbuchstaben im „value“ des zurückgelieferten Objekts, welches die aktuelle Verbindung beschreibt. Dies kann wie folgt sein:
- „none“ – No connectivity at present
- „mobile“ – Cellular network connectivity (it is not possible to differentiate between 2G/3G/4G)
- „wifi“ – Wi-Fi connectivity
Beispiel:
call: 'connectivity',
success: function (result) {
if(result.value === "wifi") {
alert("You currently have a wi-fi connection!");
}
}
});
Lautstärken Level
Liefert die aktuelle, am Gerät eingestellte Lautstärke des Streams. Beachten Sie, dass dies das für den radioplayer Stream gilt, allerdings nicht unbedingt für das Klingeln oder andere Streams.
Call: volume
Arguments: none
Returns: Eine Kommazahl zwischen 0 und 1, basierend auf der minimalen und maximalen Lautstärke des Geräts.
Beispiel:
call: 'volume',
success: function (result) {
if(result.value > 0.5) {
alert("Volume is more than halfway!");
}
}
});
Akkustand
Liefert den aktuellen Akkustand des Geräts.
Call: battery_level
Arguments: none
Returns: Eine Gleitkommazahl zwischen 0 und 1, welche den aktuellen Akkustand des Geräts sagt (1 bedeutet, dass der Akku voll ist).
Beispiel:
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
Nach Installation der App registriert diese eine 32stellige Hexadezimal-Ziffer (128 bit), welcher der Globally Unique Identifier (guid) ist. Dieser ist einzigartig in der radioplayer App und ist aktiv, so lange die App installiert ist. Sie können diese ID zur Identifizierung eines Unique Users, wenn auch völlig anonym, verwenden. Eine häufigere Verwendung für die GUID ist für den Login oder andere Funktionen, an die sich die App bei einem User „erinnert“.
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
Beispiel:
call: 'get_guid',
success: function (result) {
alert("My unique ID is: " + result.value);
}
});
App Version
Beschreibt die Version der nativen radioplayer App. Dies ist vor allem bei Veränderungen der API sinnvoll.
Call: app_version
Arguments: none
Returns: Einen String der die Nummer der Version enthält, z.B.: 1.3.2
Beispiel:
call: 'app_version',
success: function (result) {
alert("This is version " + result.value + " of the Radioplayer mobile app");
}
});
Die App betreffend
Pause
Pausiert den aktuellen Stream, wenn dieser gerade gespielt wird.
Call: pause
Arguments: none
Returns: nothing
Beispiel:
call: 'pause',
error: function(message) {
alert("Pause request failed: " + message);
}
});
Play
Spielt den aktuellen Stream, wenn dieser pausiert oder gestoppt wurde.
Call: play
Arguments: none
Returns: to be defined
Beispiel:
call: 'play',
error: function(message) {
alert("Play request failed: " + message);
}
});
Stream wechseln
Fordert, dass die App den Stream zu einem anderen ändert. Wenn diese Änderung erfolgreich war, beginnt der Stream zu spielen. Anmerkung: Wir wollen vermeiden, dass Streams zu derselben Domain wie der default Stream des Senders gesendet werden.
Call: change_stream
Arguments: A Stream URL as the „url“ value in a key/value pair.
Returns: nichts. Wenn der die Ausführung nicht erfolgreich war, wird die „error“ Call-back Funktion aufgerufen.
Beispiel:
call: 'change_stream',
url: 'http://icecast.commedia.org.uk:8000/soundart.mp3',
error: function(message) {
alert("Stream change request failed: " + message);
}
});
Sender wechseln
Wechselt den aktuellen Sender im radioplayer innerhalb der Elterngruppe. Bei dieser Aufruf wird nicht nur der Stream gewechselt. Wenn aufgerufen, verhält es sich so, als hätte der User den Sender über die Benutzeroberfläche geändert. Der Stream ändert sich und der neue Sender wird zu den Voreinstellungen, falls noch nicht vorhanden, hinzugefügt. Die Pull-down wird mit den Informationen des neuen Senders aktualisiert.
Call: change_station
Arguments: A station ID as the „id“ value in a key/value pair.
Returns: nichts. Anmerkung: Ein Error wird geworfen, wenn die ID nicht einer Sender ID innerhalb derselben Elterngruppe, die aktuell gespielt wird, entspricht.
Beispiel:
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
Die folgenden Events können von Entwickeln über die „registerEventCallback“ Methode der API (Dokument oberhalb) gefangen werden.
Die Parameter, die für diesen Event-Handler benötigt werden sind ein JavaScript Objekt mit Minimum einem Attribut: „event_type“. Bei manchen Events wird dieses Objekt ebenfalls ein „value“ Attribut enthalten.
App in den Vordergrund schieben
Dies wird kurz nachdem die Anwendung in den Vordergrund gerückt wurde aufgerufen, und nach einer Zeit in den Hintergrund.
event_type: app_foreground
Additional attributes: none
App in den Hintergrund schieben
Dies wird aufgerufen, wenn die Anwendung in den Hintergrund geschoben wird (z.B. wenn eine andere App geöffnet, der Home Button gedrückt oder wenn ein eingehender Anruf angenommen wird). Dieses Event wird aktuell überprüft.
event_type: app_background
Additional attributes: none
Lautstärke ändern
Dies wird aufgerufen, wenn die Lautstärke des Streams am Gerät vom User umgestellt wird. Es beinhaltet eine Zahl von 0 (min.) und 1 (max) im „value“ Parameter.
event_type: volume_change
Additional attributes: „value“ – float between 0 and 1, (e.g. 0.3)
Beispiel:
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);
}
});
Ändern des Play-Status
Wird aufgerufen, wenn der aktuelle Stream pausiert oder gestoppt ist.
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)
Metadaten Update Event
Wird aufgerufen, wenn der Stream die Metadaten updated, wie der Stream gespielt wird. Ein typischer Anwendungsfall wäre ein up-to-date „Now Playing“ am Display des Sender-Screens anzuzeigen.
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",
}
}
Verbindung ändern
Wird aufgerufen, wenn die Verbindung des Gerätes geändert wird.
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
Beispiel:
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?!);
}
}
});