Version 1.0.2 | API documentation

This document describes our recommendations for designing and building Station Screen HTML pages for the Radioplayer mobile apps.

Submitting your Mobile App Station Screen to Radioplayer

There are two ways. If you submit XML to Radioplayer, you should upgrade the xml metadata feed to use the new schema in order to submit a URL of the custom web view. Once this is ingested, this will filter through to the app and the web view will become visible when the station is played in-app. If you don't submit metadata by FTP then just login to the Station Control Panel and edit your station record. The field is on the Devices tab.

How to test the mobile app station screen in situ

You can test the mobile app station screen by finding the appropriate station in the mobile app and viewing its station page. So long as the above has been followed, it will appear. There is no dev environment available so changes you make will go live to the public if you update the URL specified above. Some stations are using IP detection to assist with testing - set the web view URL to an IP sniffer and redirect to a 'live' version for the public and a 'dev' version for station staff.

Sample mobile station screens

Download and edit the default mobile app station screen HTML page to begin. When opened in a desktop browser, the page doesn't look very special because it's designed to only work in the mobile app. The app provides the page with relevant metadata which makes it come to life

We have also built some small sample web-views to demo the API to the native app (note they will NOT work as expected outside of the Radioplayer app). Please take a look at the javascript at the bottom to see how these work.

  • Including a mobile advert
  • Up-selling to a radio-station's own app, after one minute of listening

Links to the samples can be found at the end of this article.

Sizes to work to

Our recommendation is to work to a minimum width of 320px for your page, but to allow it to grow to the device width. The height is subject to a lot of difference across different devices - particularly Android handsets, though a good "fold" marker for more common phones such as the iPhone, is approximately 380px. Bear in mind that this screen will be shown to users on tablets as well as phones - and in portrait and landscape so a responsive design is essential.

The smallest screen size we need to support is on the QVGA HTC Wildfire, which gives a viewport of 240px wide by around 230px high.

We recommend using the "viewport" meta tag, setting the width to "device-width". This will allow the device to grow/shrink the page to match the full width of the device's screen. In our sample we also disable pinch/zooming using the following tag, though the decision to allow zooming is up to you:

Because of the wide - and constantly changing - range of screen sizes, it may make sense to use user-agent sniffing to lay out more complex web-views if responsive design is not viable.

Minimum device list

The Radioplayer app is built for the following set of devices (these are the test devices and illustrate the minimum specification of devices upon which the apps should run):

iOS

  • iPhone 3GS - 320 x 480 px
  • iPhone 4 - 640 x 960 px
  • iPhone 4S - 640 x 960 px
  • iPad - 1024 x 768 px
  • iPad 3 - 2048 x 1536 px

Android

  • HTC Hero - HVGA - 320 x 480 px
  • HTC Wildfire - QVGA - 240 x 320 px
  • Samsung Galaxy S2 - WVGA800 - Android v2.3.5 - 480 x 800 px
  • HTC One X - 720 x 1280 px
  • Nexus S - WVGA800 - 480 x 800 px

Safe-areas

We recommend a safe area of 20-30 pixels around the edges of the HTML page to avoid accidental tapping of navigation elements.

There are no other safe-area recommendations

Interacting with the Radioplayer app

We have provided and documented a Javascript API for you to use in order to interact with the native Radioplayer app. It's platform independent and provides methods to query the native app, listen to events sent by the app, and command the app to do various things.

Details on how to use the API are included in the documentation.

Linking policy, and internal linking

In this version of the Radioplayer app, we have taken the decision to enforce links to open in the external device browser by default. This has been done for security/reliability reasons, and as a safeguard against poor user interface.

If you'd like to override external linking (for example if you want to include an iframe with an ad in it), you can include a special string "rpwv-int" in the URL. At native app level the presence of this string in the link indicates that the link should appear within the same web-view.