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. You are strongly advised to read this guide in conjunction with the User Guide.
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.
These are found near the top of index.html
currentStationID and currentStationName must be set to your Radioplayer ID and station name.
Contact station.support@radioplayer.co.uk 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:
If you wish, the contents of the bar can be locked to specific source.
Other options for nowPlayingSource include:
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.
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.
audioArray contains the options for the stream(s). You can specify one or many streams and the console will detect the capabilities of the device and will work its way through the array.
audioType can be one of 'playlist', 'http', 'httpmp4m4a', 'rtmp', 'aac' or 'hls'audioUrl should be set for playlist, http and httpmp4m4a, 'aac' or 'hls.audioServer and audioEndpoint should be set for rtmp.bufferTime can be adjusted if necessary.
cacheKiller: true can be added to audioFlash, to add a cache busting parameter to the end of the stream, although this is not usually necessary.
For audioType 'playlist', the following playlist formats are supported: SMIL, ASX, XSPF, PLS, M3U. Links to 'playlists within playlists' are also supported.
The other audioTypes are explained as follows
'http' is to be used for all MP3 streams - shoutcast and icecast and is supported in devices that have Flash or are HTML Audio only
'httpmp4m4a' is to be used for FLV-encapsulated MP4 streams (eg. AAC streams). Supported in Flash only and encapsultation is compulsory
'aac' is to be used for un-encapsulated AAC streams. Supported in HTML Audio but not Flash devices.
'hls' can be used if you wish to use the experimental support for HLS. Supported on devices with Flash only and the URL should be an m3u8 playlist.
'rtmp' - RTMP streams with 'server-endpoint' configurations are only configurable in playlists when using XSPF and SMIL formats. RTMP support is limited to devices which support Flash only
The console will by default attempt to play audio with Flash if the device supports it, and will fall back to HTML Audio if need be. This behaviour is recommended because Flash is more resilient to stream inconsistencies. However if this behaviour needs to be reversed you can change preferredPlaybackMethod to 'html';
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
The plugin space can be full customised. It is found towards the bottom of index.html and clearly marked by start and end comments. Two types of plugin spaces are allowed - fixed width or responsive. By default, the plugin space is set for fixed-width plugin spaces. If you have a responsive plugin space, set the flag var isResponsive = true;
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.
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.
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.
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]].
The overlay is mainly used for video ads in this version of the console, which means that if you want to use it for something else and you also run video ads, it's worth knowing that the video ads will always take priority and will eject any overlay content which already exists, if a video needs to run.
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.
There is now support for AdsWizz and VAST video ads
The console is built with libraries that support both VAST 2 and VAST 3. When a console is configured for VAST, it will open as normal, make a call and if there is a VAST response then the console will resize, play the video and revert to its native size when the video has finished. Of course, if the console has not opened in a popup, the resizing parts of this will not take place. The video will be displayed in a space which is up to 640px wide and 480px high. It should be noted that the VAST response must contain a reference to a playable video asset. Do not use SWF's as ads or ad containers. It's not possible to track or render them correctly.
Companion ads are supported and will be displayed below the video player when they are defined in the ad response. It should be noted that a limited amount of space exists below the video player and we recommend a maximum size of 700px x 100px to prevent layout breakages or unexpected scrolling.
To configure your console, you will require your vast ad tag. This looks something like
http://my.adprovider.com/path/to/vasttag.xml
Edit the console's index.html file and locate the code block below
var vastAds = {
enabled: false,
vjsSkin: 'vjs-default-skin',
vastTag: 'VAST_TAG_URL'
};
Update this block with your VAST ad tag URL and ensure the enabled flag is set to true to give something like this:
var vastAds = {
enabled: true,
vjsSkin: 'vjs-default-skin',
vastTag: 'http://my.adprovider.com/path/to/vasttag.xml'
};
It is possible to change the styles of the VST video player by changing the value of vjsSkin and specifying your own stylesheet. This is not recommended and you should leave as is. Ensure the value for enabled is not enclosed in quotation marks.
Once editing is complete, save the index.html file and replace your existing version with this one. A VAST ad will then be called whenever the console is loaded.
The Radioplayer console is also AdsWizz-enabled out of the box. AdsWizz, at the time of writing, offer two solutions - a client-side solution and the more popular server-side solution. In the case of a client-side solution, adverts are delivered via VAST and the framework explained above will allow a station to deploy that.
However for stations using the server-side solution (whereby ads are injected into a listeners' stream at the start of - and during the stream) the console can be configured to respond to this. Like VAST, a companion ad is available but only available when the console is using Flash as a playback engine since the HTML5 player cannot extract the metadata from the stream. In this solution the companion ad is permitted to occupy up to the full size of the plugin space. A station, during their setup with AdsWizz will determine what sizes of companion ads they wish to support. This allows everything from a simple MPU to a rich media experience in the plugin space.
To configure the console you will need:
Edit the console's index.html file and locate the following code block:
var adsWizz = {
enabled: false,
domain: 'ADSWIZZ_DOMAIN',
prerollZoneId: PREROLL_ID,
midrollZoneId: MIDROLL_ID,
playerId: 'UKRP'
};
Replace the placeholders with your hostname, preroll ID and midroll ID so ending up with something like this:
var adsWizz = {
enabled: true,
domain: 'myadswizzdomain',
prerollZoneId: 11111,
midrollZoneId: 22222,
playerId: 'UKRP'
};
Ensure the enabled flag is set to true and that only the domain and playerId value should be in quote marks. The rest are boolean and numeric, so should be stated as such.
The index file can then be saved and replaced on the server.
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();
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
You can enable the javascript debug very easily by appending ?debug=true to any console URL. The debug information for both the console and the flash EMP will be output to the javscript console.
The console also supports a staging mode. This is detailed in more depth, in the User Guide. Once you have been issued a development host, you can set it as a querystring param devapi=RPDEV_DOMAIN_NAME
Editing the first-run cookie announcement
The first-run cookie announcement is defined in the index.html file. The panel is shown to users the very first time they use the Radioplayer console (or if they've recently cleared cookies). The copy provided is adequate to comply with UK law but if you need to add to it, you can do so. To change the link that the copy clicks through to, edit /js/lang-en-gb.js and edit the value of cookie_link
Radioplayer does not use jQuery's "no conflict" mode.
The console is currently using v1.10.0, as .1 and .2 causes an issue with cross domain iframes on Safari and IE. If using later version, test these browsers and look for SCRIPT5 errors.
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.
<a href="http://player.example.com/" data-newstationid="XXXX">My other station</a>