Native Media Player

Background Audio Player for iOS & Android

The background audio Native Media Player adds a native media player UI to the device lock screen and notification area. This allows audio from your app to play while the device is locked or your app is backgrounded. Use cases include radio apps, audiobooks, podcasts, e-learning courses, corporate training, news publications, and many more. The player includes Play/Pause and Previous/Next controls, and displays metadata associated with the currently playing track. The player receives either a single track or an array of tracks (playlist) from your website through the GoNative JavaScript Bridge.

Implementation Guide

On the website, to pass audio URLs, you will need to use the following native JavaScript Bridge functions:

Play a single track

HTML:

<button type="button" onclick="streamTrack(track)">Start Track</button>

JavaScript:

️GoNative JavaScript Bridge

Create an object with the URL of the track:

var track = {
      "url": "https://Your_Audio_URL"
}

OR

Create an object with the URL of the track and custom metadata (if your audio does not include already):

// track with metadata
var track = {
     "url": "https://Your_Audio_Url",
      "title": "Example Title",
      "album": "Example Album",
      "artist": "Example Artist"
}

// function to load track to player via JavaScript Bridge:
function streamTrack(track) {
       window.location.href = "gonative://backgroundMedia/playTrack?track=" + encodeURIComponent(JSON.stringify(track));
}

When playing a single track, the will display Play/Pause and Close buttons.

iOS - Single Track Android - Single Track

Play a Playlist

HTML:

<button type="button" onclick="streamPlaylist()">Start Playlist</button>

JavaScript:

️GoNative JavaScript Bridge

Create an object with any number of audio tracks to send to the device as one playlist along with the starting track number in currentTrackNumber. For example, to start the playlist with the 3rd song in the playlist, set the currentTrackNumber: 2.

var playlist = {
     "currentTrackNumber": 0,
     "tracks": [
               {
                   "url": "https://Your_Audio_URL_1",
                   "title": "Example 1 Title",
                   "album": "Example 1 Album",
                   "artist": "Example 1 Artist"
               },
               {
                   "url": "https://Your_Audio_URL_2",
               },
               {
                   "url": "https://Your_Audio_URL_3",
                   "title": "Example 2 Title",
                   "album": "Example 2 Album",
                   "artist": "Example 2 Artist"
               }
       ]
}

// access native bridge and pass the callback function
function streamPlaylist() {
      window.location.href = "gonative://backgroundMedia/startPlaylist?callback=startPlaylistCallback";
}

// this callback function will be called by the device to retrieve the queue
function startPlaylistCallback() {
      return playlist;
}

Move through playlist

When the currently playing track finishes playing, the player will automatically switch to the next track in the playlist. The user can also step through the playlist using the Next and Previous buttons.

iOS - Playlist Android - Playlist

Audio Metadata

The player will display the embedded metadata of the playing track, including the audio icon image. If your audio file does not include any metadata, you can include the metadata in the track object, as shown in the examples above.
Note: If metadata is embedded in the track but also provided manually, the manual metadata will be selected.

If no metadata is available, the metadata will be set as:
Title: Playing Media
Album: APP_NAME
Artist: APP_NAME

iOS - Default Metadata Android - Default Metadata

Audio icons can only be retrieved directly from the Audio URL. So, if none is available, the MediaPlayer will set the app icon as the audio icon:

Audio icon from embedded metadata:

Default audio icon - App Icon:

iOS - Default Audio Icon Android - Default Audio Icon

Stop MediaPlayer

HTML:

<button type="button" onclick="stop()">Stop</button>

JavaScript:

️GoNative JavaScript Bridge

Declare a function to load the javascript bridge URL:

function stop() {
      window.location.href = "gonative://backgroundMedia/stop";
}

Note: For Android, this command will stop the background media and remove the Media Player from the notification area. For iOS, it will only pause the media.