Embedded Player Documentation

What is the Embedded Player?

The Embedded Player is a limited functionality implementation of the Radioplayer Web Player which rather than being served as a standalone pop out player, can be integrated into a third party website. A button can be embedded into the third party website which on first click shows the docked embedded player bar and controls at the bottom of the screen. Subsequent clicks control the audio stream Play/Pause and the state of the embedded button is synced with the embedded player controls.

Components

All components specifically created for the Embedded Player are located in the src/components/EmbeddedPlayer/ directory. Some additional components have been reused from the existing Radioplayer component library, where additional behaviour/properties have been required for the new use case, care has been taken to ensure the existing behaviour of the component is maintained as default.

Embedding the Components

Three components can be embedded directly onto a third party website with embeddedplayer.js and embeddedplayer.css bundles being served via CDN. Webpack is configured to output the embeddedplayer namespace using src/index.embedded.ts as the entry point.

Preact Habitat is used to render the following components with the JSON providing props. The console generator has been extended to allow stations to configure and download their html accordingly.

The following is an example of Fun Kids configuration.

Embedded Player Button

        <div class="player-embedded-button">
            <script type="application/json">
                {
                    "primaryColor": "#008aff",
                    "secondaryColor": "#FFFFFF"
                }
            </script>
        </div>

Embedded Popup Controller

Please note, in order to ensure this component docks correctly to the bottom of the page, it must be inserted as a direct child of the <body> element

        <div class="player-embedded">
            <script type="application/json">
                {
                    "id": "1004",

                    "fallback": [
                        {
                            "url": "https://media-the.musicradio.com/LBCUKMP3",
                            "format": "mp3"
                        }
                    ],
                    "mapi": "https://mapi-prod.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/",
                    "stationLogo": "https://assets.radioplayer.co.uk/stationimages/1004_handheld_default_square_image600.png",
                    "localeRootUrl": "https://assets.player.radio/latest",
                    "primaryColor": "#008aff",
                    "secondaryColor": "#FFFFFF",
                    "theme": "DARK",
                    "dockRight": false,
                    "stationUrl": "https://www.funkidslive.com/",
                    "theme": "DARK",
                    "domainName": "https://radioplayer.co.uk",
                    "availableApps": {
                        "logo": "https://cdn-ssl.funkidslive.com/wp-content/themes/funkidslive/_img/logo-sm.png",
                        "title": "You can now take Fun Kids with you EVERYWHERE!",
                        "description": "The app is chock-a-block with all of the Fun Kids goodness in one handy place.",
                        "iosLink": "https://itunes.apple.com/gb/app/fun-kids-radio/id1126823471?mt=8&uo=8&at=1l3v7pW",
                        "playLink": "https://play.google.com/store/apps/details?id=com.funkidslive"
                    }
                }
            </script>
        </div>

Embedded Inline Advert

        <div class="player-embedded-advert">
            <script type="application/json">
                {
                    "primaryColor": "#008aff",
                    "secondaryColor": "#FFFFFF",
                    "adSize": "leaderboard"
                }
            </script>
        </div>

Lib

Some additional hooks, context and providers have been created to encapsulate functionality and reduce the depth at which props need to be cascaded. They are as follows:

Embedded Player Context and Provider

The business logic for controlling the audio stream is abstracted into it's own context and provider. Full details of this can be found here.

Adverts Context and Provider

The business logic for managing and displaying adverts is abstracted into it's own context and provider. Full details of this can be found here.

usePlayerChannel

This hook manages communication between components which do not have a common parent node in the DOM and cannot cascade props or take advantage of a central store. Full details of this can be found here.

Embedded Player Props

Console generator fields

The logo used on the player control bar

Station URL

The url the logo will navigate to on click

Primary Colour

The base colour of the embedded player

Secondary Colour

The colour used for fonts and icons

Dock Right

If the player should dock to the right of the screen

Available Apps

The object used to populate the menu item linking to the App Stores:

  • Logo - The app logo image
  • Title - The name of the App
  • Description - A short description of the App
  • iOS App Store Link - The link to the IOS store (Optional)
  • Google Play Store Link - The link to the Play Store (Optional)

Generate Console Request Object

{
    "stationLogo": string // Base64 encoded
    "stationUrl": string
    "primaryColor": string
    "secondaryColor": string
    "dockRight": boolean
    "availiableApps: Array<{
        "logo": string
        "title": string
        "description": string
        "iosLink": string
    }>

}