Preface
This is an advanced document is aimed at a technical audience and is suited to those who are using the Reference Console. If you’re not – or don’t think you are – then you should follow the Getting Started pages instead.
This document is a snapshot of the integration guide as at the time shown above. Check your Reference Console release for the latest version.
Radioplayer v3 Integration Guide
This guide will help you customise the Radioplayer console for your station. Generally, there should be no need to change any part of the player other than those sections referred to below.
Theme
The station logo and background image or colour can be set in style/theme.css
If you choose to have a dark background, you will need to change the controls to the light variation. To do this, open index.html and scroll to the line which begins div class=radioplayer. You will see dark-theme by default, which can be changed to light-theme.
You must also update the station logo link to point to your website, and the accessibility text containing your station name. To do this, look for the line in index.html which begins a class=”stn-logo” and update the ‘href’ parameter to your website URL, and replace the two instances of ‘Your Station Name’ with your station name.
Settings
These are found near the top of index.html
currentStationID and currentStationName must be set to your Radioplayer ID and station name. Contact station.radioplayer.ca if you do not know your Radioplayer ID.
nowPlayingSource can be left as default. This setting changes the behaviour of the ‘now playing’ bar.
By default, the console will attempt to fill the bar by checking these sources, in this order:
- The current track playing, provided as PE to Radioplayer.
- The current programme on air, provided as PI to Radioplayer.
- The metadata coming from the live audio stream.
- The station description, provided in SI to Radioplayer.
- The station name, provided in SI to Radioplayer.
If you wish, the contents of the bar can be locked to specific source. Other options for nowPlayingSource include:
- ‘default-no-stream’ – this uses the default behaviour listed above, but doesn’t look at the stream for metadata.
- ‘stream’ – this uses the metadata in the stream only.
- ‘SI’ – this uses either the station description (if provided) or name from your SI provided to Radioplayer.
- ‘PI’ – this uses the programme name provided to Radioplayer via PI.
xDomainProxyUrl must be set to the full URL to the xdomainproxy.html file, which by default is found in the preroll-framework directory. This file is utilised if a preroll overlay is enabled.
initOptions contains 3 options, which if enabled will override their corresponding settings in Radioplayer central systems. Full details on these options are in the Commercial Settings section below.
Stream
The settings for the stream or On Demand audio are found near the top of index.html
audioLive should be set to true for live streams or false for on demand audio.
audioFlash contains the options for the stream.
- audioType can be one of ‘playlist’, ‘http’, ‘httpmp4m4a’, ‘rtmp’.
- audioUrl should be set for playlist, http and httpmp4m4a.
- audioServer and audioEndpoint should be set for rtmp.
bufferTime can be adjusted if necessary.
For audioType ‘playlist’, the following playlist formats are supported: SMIL, ASX, XSPF, PLS, M3U. Links to ‘playlists within playlists’ are also supported.
RTMP streams with ‘server-endpoint’ configurations are only configurable in playlists when using XSPF and SMIL formats.
If you have a stream which is supported by browsers which can play audio without Adobe Flash Player being installed, you can specify the parameters for audioHTML. RTMP format is not supported in this scenario. The audioHTML stream will be used by a browser which does not have Flash, or on a device which it is not possible to install Flash, for example an iPad.
Some streams/playlists may not play if there are security errors due to your streaming provider not implementing Adobe’s crossdomain policy permissions.
Here is a sample Adobe crossdomain policy file which you can send to your streaming provider, should there be crossdomain issues with your stream or playlist. It is provided separately in the full Radioplayer zip.
<?xml version="1.0" ?>
<!DOCTYPE cross-domain-policy (View Source for full doctype...)>
<cross-domain-policy>
<site-control permitted-cross-domain-policies="all" />
<allow-access-from domain="*.example.com" secure="false" />
<allow-http-request-headers-from domain="*.example.com" headers="*" secure="false" />
</cross-domain-policy>More information is available here:
http://learn.adobe.com/wiki/download/attachments/64389123/CrossDomainPolicyFileSpecification.pdf?version=1
Plugin Space
The plugin space can be full customised. It is found towards the bottom of index.html and clearly marked by start and end comments.
Playing Audio Clips
An audio clip can be played in the console by simply adding to the console URL ?rpAodUrl= followed by the URL of the audio file. The console will attempt to source ‘now playing’ information for this, firstly from central systems and secondly by looking at any ID3 metadata in the audio file.
Commercial Settings
The initOptions object found in the head of index.html allows you to enable 3 commercial settings for your console. These options can also be enabled in Radioplayer central systems.
Interstitial
Change enabled to true, to enable an Interstitial, and complete url with the URL for your interstitial page. The interstitial will appear when the console is launched, but not when navigating from one Radioplayer to another.
You can use the template provided in preroll-framework/index.html to add a Skip button, and handle redirecting back to your console without being shown the interstitial again.
Song Action
A Song Action is a small button which appears to the right side of the ‘now playing’ strip while a song is playing. The button can link to a URL of your choice, with the artist and/or title being passed along in the query string.
Change enabled to true to enable a Song Action. type should contain the text for the button. baseurl should contain the URL which will be opened in a new browser window when the button is clicked.
If you need to pass the artist or title of the song playing to the URL, they can be inserted by using the placeholders [artist] and [title]. For example, http://www.song-retailer.com/buy.php?artist=[artist]&title=[title].
If you need to insert the artist or title into a ‘URL within a URL’, you may require double encoding. If this is the case, you can use [[artist]] and [[title]].
Overlay
Change enabled to true, to enable an Overlay, and complete url with the URL for your overlay page. The overlay will appear when the console is launched in live mode, occupying the plugin space. Change mute to true, if you wish the stream audio to be muted while the overlay is visible.
You can use the template provided in preroll-framework/index.html to add a Skip button, and handle closing the overlay. If you opt to have the stream muted, the built-in skip method will handle unmuting the audio for you.
Advanced Topics
Showing an Overlay at any time
You can show an overlay at any time, by making a JavaScript call to:
radioplayer.services.showOverlay(‘http://www.example.com’, true);
The first parameter is the URL for the overlay, and the second parameter should be true/false for whether the stream should be muted.
You can manually hide an overlay from the console, by making a JavaScript call to:
radioplayer.services.hideOverlay();
Internationalisation
Text in Radioplayer is stored in js/lang-en-gb.js
To change the language, create a copy of this file, alter the strings inside for the new language, and then update the reference in index.html to point to your new language file.
You should also update the 6 instances of lang=”en” at the top of index.html to reflect the new language. Information regarding the lang attribute is available at http://www.w3schools.com/tags/ref_language_codes.asp
API Documentation
For advanced documentation on the JavaScript codebase, view the integration guide provided with the console and a link will be shown here instead
jQuery
Radioplayer does not use jQuery’s “no conflict” mode.
Sideways Navigation
If you have a link in your plugin space to navigate from one console to another, there’s an attribute data-newstationid which you should add to your link tag so that it can be tracked for analytics purposes. The following is an example of a link, where XXXX should be replaced with the destination player’s Radioplayer ID.