Integrating the player in a CMS

The Radioplayer web player can be integrated into a CMS by altering the JSON inside the tag. This is most useful for on demand content, as it allows the full details of the content to be passed in, without needing a lookup. The player cannot be displayed inline in another page: it must be displayed alone in a popup, with no extra elements such as navigation or ads on the page. If you attempt to embed it with other elements then this is likely to break the display and is a breach of the terms of use. Ads can be displayed by the player, and if custom content is required then the correct approach is to use an embedded iframe widget.

The easiest way to display it in a popup is to use a launcher button. However, if required you can manually launch it into a window. The standard size is 960 pixels wide and 700 pixels high. This allows three widgets to be displayed. You may use a narrower window if you are displaying fewer widgets, or a custom iframe, but it should never be narrower than 380 pixels.

Integrating the player

You must first link the player scripts and stylesheet in the <head> of your page:

<script
    type="module"
    src="https://assets.player.radio/latest/radioplayer.js"
></script>
<script
    nomodule
    defer
    src="https://assets.player.radio/latest/radioplayer.legacy.js"
></script>
<link
    rel="stylesheet"
    href="https://assets.player.radio/latest/radioplayer.css"
/>

There are two versions of the script included, with the smaller module version served to modern browsers, and the legacy version served to older browsers. This ensures that most users can use a faster-loading version, while still supporting older browsers. The scripts are loaded asynchronously, so the tags can (and should) be placed in the <head> without blocking page loading.

You should add the following CSS. For best performance, include it in the <head>. However you could include it in your common stylesheet if required.

[data-widget-radioplayer] {
    /* These properties are required */
    width: 100vw;
    height: 100vh;
    left: 0;
    top: 0;
    position: absolute;
}

The player is integrated by creating a tag with a data-widget-radioplayer property:

<div data-widget-radioplayer>
    <!-- ...  -->
</div>

The player then needs to be configured, to ensure that it loads the correct station. This is done by inserting a JSON object into a script tag inside the widget. Note the type attribute: it is application/json, not javascript.

<div data-widget-radioplayer>
    <script type="application/json">
        {}
    </script>
</div>

There are several configuration options that you can use, but the minimal required for a live player is the following:

<div data-widget-radioplayer>
    <script type="application/json">
        {
            "id": "350",
            "fallback": [
                {
                    "url": "http://bbcwssc.ic.llnwd.net/stream/bbcwssc_mp1_ws-eieuk",
                    "format": "mp3"
                }
            ],
            "mapi": "https://mapi.radioplayer.co.uk/api/uk/",
            "cm": "https://cookie.radioplayer.co.uk/cm/",
            "np": "https://np.radioplayer.co.uk/qp/",
            "qp": "https://search.radioplayer.co.uk/qp/"
        }
    </script>
</div>

See the configuration guide for details of the options.

Optimising performance

The Radioplayer web player is a highly-optimised web app out of the box, with an initial JavaScript payload of under 50kB and very fast rendering times. However we recommend adding several extra tags to the page <head> to further optimise load times for the player. These ensure that critical resources are preloaded, so that the player is ready to play as soon as possible. These tags will be automatically added by the console generator, but if you are integrating the player yourself you can cut load times by several hundred milliseconds by adding them. The following tags should be added to the <head>, directly below the <script> tags, which should be at the very top.

<link
    rel="preload"
    as="font"
    crossorigin
    type="font/woff2"
    href="https://assets.player.radio/latest/assets/sintony-v7-latin-700.woff2"
/>
<link
    rel="preload"
    as="fetch"
    crossorigin="use-credentials"
    href="locales/en/translation.json"
/>
<link rel="preconnect" href="https://mapi.radioplayer.co.uk/" />
<link
    rel="preconnect"
    href="https://np.radioplayer.co.uk/"
    crossorigin="use-credentials"
/>
<link
    rel="preconnect"
    href="https://search.radioplayer.co.uk/"
    crossorigin="use-credentials"
/>

The URLs in the preconnect links are the ones that you pass in as configuration properties, and should be changed to match the URLs in your configuration. The preload locale link should point to your translation file.

If you serve your console over HTTPS then the player will register a service worker to further optimise performance of both the player and HTTP live streams. However serving the console over HTTPS may not work if the streams are not also served over HTTPS.

Radioplayer Integration Guide

Integrating the player in a CMS

Integrating the player

Optimising performance