radioplayer

Technische Dokumentation: Webview 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:

 

<!– Radioplayer Bridge –>
<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:

 

 // pause the stream
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:

 // 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);
}
});

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:

    // 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);
});

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:

„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/86×48/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:

 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();
}
});

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:

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

Beispiel:

 RPBridge.sendToDevice({
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.

Beispiel:

 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);
}
});

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:

 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);
}
});

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:

 RPBridge.sendToDevice({
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:

  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

Beispiel:

 RPBridge.sendToDevice({
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:

 RPBridge.sendToDevice({
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:

 // 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

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:

 RPBridge.sendToDevice({
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:

 RPBridge.sendToDevice({
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:

 RPBridge.sendToDevice({
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:

 RPBridge.sendToDevice({
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:

 RPBridge.sendToDevice({
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:

 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

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:

    // 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);
}
});

Ä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

  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)

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:

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

Beispiel:

    // 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?!);
}

}
});

Stay up to date!