Documentation

Working With Apache Cordova

Get started with Apache Cordova

Apache Cordova is an open-source command-line solution that allows to build mobile applications with web technologies (HTML, CSS, JavaScript). We will review in this article how to use Radiant Media Player in a Cordova-based mobile application.

Scope of support

We support the following environments for using Radiant Media Player with Apache Cordova:

  • Apache Cordova 9+
  • Android 5+
  • iOS 10+ (WKWebView)
  • iPadOS 13+ (WKWebView)

When using Radiant Media Player in a production Cordova-based application we recommend using self-hosting of player files within the application for better performance. Active customers can download the self-hosted package in our back-end. Trial users can use the cloud player for testing purposes.

With the announcement of Apple in december 2019, to remove support for UIWebView API by end 2020, we only support WKWebView API for iOS apps built with Cordova or Ionic. See this blog post to help you update to WKWebView API.

Installing Apache Cordova and other dependencies

In order to install Apache Cordova follow the instructions on its home page.

Once this is done we will create a new project as follows:

cordova create rmpsampleapp com.radiantmediaplayer.rmpsampleapp RmpSampleApp

This will create a Cordova project with a basic structure to help us get started. Our application name is RmpSampleApp and is located in folder rmpsampleapp/.

Now we will navigate to our application folder (rmpsampleapp/) and we will add platforms that we want to target for development our application:

cd rmpsampleapp
cordova platform add browser
cordova platform add android
cordova platform add ios

Here we add the browser, Android, and iOS platforms. To check your current set of platforms use:

cordova platform ls

To build and run an application on a specific platform, you will need to install SDKs for this platform. The browser platform which can conveniently be used for development does not require any platform SDKs. To check if you satisfy requirements for building on a specific platform use:

cordova requirements

You can review the following articles for information on building for Android or iOS: Android platform requirements and iOS platform requirements.

When our application is ready we can use an emulator to test our application. For example for Android:

cordova emulate android

or we can compile and transfer our application on a real device. For example for Android:

cordova build android

But before we do that we will need to develop our application and add Radiant Media Player to it. There are many other options with Apache Cordova, including various plugins designed to fit features available in native applications. It is not the purpose of this guide to cover a comprehensive tour of Apache Cordova but rather we would like to provide enough information to easily implement Radiant Media Player in a Cordova-based mobile application.

Installing and updating Apache Cordova and its dependencies in order to build a mobile application may require advanced tuning based on your development and target platforms. Radiant Media Player support team cannot help with installing or troubleshooting Apache Cordova set-up.

Developing our application

Project structure

When we ran the cordova create rmpsampleapp com.radiantmediaplayer.sampleapp RmpSampleApp command line we created a blank Cordova project. You can review the project structure in the rmpsampleapp/ folder.

This should look like:

  • hooks/
  • platforms/
  • plugins/
  • res/
  • www/
  • config.xml
  • package.json

Now we will take a closer look at the www/ folder which holds our web-application to be rendered in a native mobile application. It has generic folders that we can find in any modern web project:

  • css/
  • img/
  • js/
  • rmp/
  • index.html

Code example

We will now modify the files within the www/ folder to add Radiant Media Player to our project.

In this example we use Radiant Media Player self-hosted player files. For the purpose of this guide those files were put under the rmp/ folder (this folder was not created by Cordova). While it is also possible possible to use our cloud player it is generally best to host the player files within the application itself when going for production for best performance.

www/index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="format-detection" content="telephone=no">
  <meta name="msapplication-tap-highlight" content="no">
  <meta name="viewport" content="initial-scale=1, width=device-width, viewport-fit=cover">
  <meta http-equiv="Content-Security-Policy" content="default-src * blob: http: https: file: data: android-webview-video-poster: https://ssl.gstatic.com 'unsafe-inline' 'unsafe-eval';">
  <link rel="stylesheet" href="css/bootstrap.min.css">
  <link rel="stylesheet" type="text/css" href="css/index.css">
  <title>Hello RMP and Cordova</title>
</head>
<body>
  <div class="container">
    <div class="row">
      <div class="col-sm-12">
        <h1>RMP in Apache Cordova</h1>
        <p>Some content before our player ...</p>
        <div id="rmp"></div>
        <br><br>
        <p>... some content after our player</p>
      </div>
    </div>
  </div>
  <script src="cordova.js"></script>
  <script src="rmp/dist/rmp.min.js"></script>
  <script src="js/index.js"></script>
</body>
</html>

Let us review the good parts of this index.html file:

Well-formed HTML document: this file uses a valid HTML5 DOCTYPE and HTML file structure with <html>, <head> and <body> sections.

Content security policy (CSP): for more information on CSP you can review this MDN article and this Cordova documentation article. CSP is an important part of successfully using Radiant Media Player in a Cordova-based application so make sure to take some time to fully understand this concept if you are not already familiar with it. The following is an example of CSP that does work with Radiant Media Player. You may find a stricter CSP configuration that works for your use-case but keep in mind that media-oriented applications often need to fetch content and resources hosted from different Internet locations.

default-src * blob: http: https: file: data: android-webview-video-poster: https://ssl.gstatic.com 'unsafe-inline' 'unsafe-eval';

Around our CSP meta tag we have various Cordova-specific meta tags which you can find documentation for in Cordova documentation.

Then we find our CSS files, in this example we use the Bootstrap CSS framework.

www/css/index.css

* {
  -webkit-tap-highlight-color: rgba(0,0,0,0);
}

body {
  -webkit-touch-callout: none;
  -webkit-text-size-adjust: none;
  -webkit-user-select: none;
  font-family: 'HelveticaNeue-Light', 'HelveticaNeue', Helvetica, Arial, sans-serif;
  font-size: 12px;
  height: 100%;
  margin: 0px;
  padding: 0px;
  width: 100%;
}

The HTML layout for our application is very basic and should speak for itself. We can find our player container with id rmp. At the bottom of our file we find JavaScript files:

  • cordova.js which is required to build applications with Cordova
  • rmp/dist/rmp.min.js Radiant Media Player self-hosted core JavaScript file
  • js/index.js which our logic to start the application and the player

www/js/index.js

const app = {
  // Application Constructor
  initialize: function () {
    document.addEventListener('deviceready', this.onDeviceReady.bind(this), false);
  },
  // deviceready Event Handler
  onDeviceReady: function () {
    this.setUpPlayer('rmp');
  },
  // set up player onDeviceReady
  setUpPlayer: function (id) {
    const src = {
      hls: 'https://your-hls-url.m3u8'
    }; 
    const settings = {
      licenseKey: 'your-license-key',
      src: src,
      width: 640,
      height: 360,
      // we tell the player where to look for the self-hosted player files
      pathToRmpFiles: 'rmp/',
      // if we need ads
      // ads: true,
      // rmp-vast is generally preferred in Cordova apps to display ads
      // but if you are using Google ads servers (Google Ad Manager, AdSense for video), the IMA SDK is required
      // see https://www.radiantmediaplayer.com/docs/latest/mobile-applications.html#mobile-video-ads
      // adParser: 'rmp-vast',
      // adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',
      contentMetadata: {
        poster: [
          'https://your-poster-url.jpg'
        ]
      }
    };
    const rmp = new RadiantMP(id);
    rmp.init(settings);
  }
};
app.initialize();

Once we have our files ready we can run:

cordova run browser

The above will let us see how our application renders in our system default browser. Then we can do:

cordova run android

And the application will be compiled and transfered to our test Android device. With proper configuration we can do the same for iOS.

Deploying to iOS specific considerations

  • Developing, testing and building your app on iOS requires a macOS device with latest Xcode installed. Refer to this Cordova documentation article for more information.
  • iOS developers need to generate a provisioning profile to code sign their apps for testing. A guide to achieving this can be found here.
  • You need to configure your Cordova application to play media content inline for the player to work as expected. This can be achieved by adding <preference name="AllowInlineMediaPlayback" value="true" /> to your config.xml file.
  • By default when an iOS device is in silent mode (the little switch above the side volume buttons) HTML5 media content is played without sound. This cordova plugin allows to work around this issue.

Managing player instances and changing content source

Projects based on Cordova often SPA frameworks (Angular ...). When using SPA you may find the following player API useful:

  • Destroying a player instance: when you are done using the player in a view you could want to destroy a player instance. This is done through the player API destroy method. This will clean up the player instance & buffer and free up memory. Once destroy has completed you can remove the player container from DOM and append/init another player at a later stage within the same view or another view.
  • Changing source: this is done through the setSrc API method. The player instance will remain the same, only the source content within the player will change which is less heavy than using the destroy method.

You can refer to our player API docs and examples for information on how to use the above methods.

Debugging

You can review the Debugging Cordova apps article to understand how to debug Cordova-based applications. More generally the Best Practices Cordova app development is a must read before doing any serious Cordova-based development.

Going further

You can review a non-exhaustive list of available features for Radiant Media Player in a mobile application built with web technologies here. You can then browse our documentation to review how to enable those features in Radiant Media Player and start building your amazing Android and/or iOS mobile application.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.

©2015-2024 Radiant Media Player. All Rights Reserved.