Documentation

Working With Apache Cordova

Get started with Apache Cordova

Scope of support

Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies - HTML5, CSS3, and JavaScript for cross-platform development. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's capabilities such as sensors, data, network status, etc. Apache Cordova can be used to build native application for Android and iOS with web technologies.

You can use Radiant Media Player with Apache Cordova to build native mobile video apps for Android or iOS while leveraging web technologies. This allows for faster time to market and reduced cost while keeping cross-platform complexity deployment manageable: no SDK - no headache.

As of Radiant Media Player 9.15 we support using our player with:

  • Apache Cordova 11+
  • Android 5.1+ with cordova-android 11+
  • iOS 11+ (WKWebView) with cordova-ios 7+
  • iPadOS 13+ (WKWebView) with cordova-ios 7+

This guide is not a comprehensive guide about how to develop apps with Apache Cordova - it is just meant as a usage example on how to use Radiant Media Player with Apache Cordova.

For platform-specific guides for using with Apache Cordova see:

When using Radiant Media Player in a production Apache Cordova application we recommend using self-hosting of player files 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.

Using Radiant Media Player in an Apache Cordova application requires a PLATFORM Edition license key. Trial users can also test using Radiant Media Player in an Apache Cordova application.

Installing Apache Cordova and creating our project

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 an Apache Cordova project with a basic structure to help us get started. Our application name is RmpSampleApp and is located in folder rmpsampleapp/.

We will now navigate to our application folder (rmpsampleapp/) and add platforms that we want to target:

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 run an application on a specific platform, you will need to install SDKs for this platform. See above for platform-specific guides.

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

cordova emulate android

We can also compile our application on a real device. For example on Android:

cordova build android

But before we do that we will need to develop our web application and add Radiant Media Player to it!

Developing our application

Project structure

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

This should look like:

  • node_modules/
  • platforms/
  • 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 should look like:

  • css/
  • img/
  • js/
  • 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. Those files were put under the www/rmp/ folder. This rmp/ folder was not created by Apache Cordova - you will have to add the Radiant Media Player self-hosted files separately. It is also possible to use our cloud player for testing purposes - in which case you do not need to add the rmp/ folder or use the pathToRmpFiles setting. 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';">
  <meta name="color-scheme" content="light dark">
  <link rel="stylesheet" href="css/bootstrap.min.css">
  <link rel="stylesheet" type="text/css" href="css/index.css">
  <title>Hello RMP and Apache Cordova</title>
</head>
<body>
  <div class="container">
    <div class="row">
      <div class="col">
        <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>
  <!-- This is our self-hosted player (recommended for production) -->
  <script src="rmp/dist/rmp.min.js"></script>
  <!-- Or with our cloud player (OK for testing) -->
  <!-- <script src="https://cdn.radiantmediatechs.com/rmp/9.15.10/js/rmp.min.js"></script> -->
  <script src="js/index.js"></script>
</body>
</html>

Let us review 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. CSP is an important part of successfully using Radiant Media Player in an Apache Cordova 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 Apache Cordova meta tags which you can find documentation for in Apache 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); // make transparent link selection, adjust last value opacity 0 to 1.0
}

body {
  -webkit-touch-callout: none; // prevent callout to copy image, etc when tap to hold
  -webkit-text-size-adjust: none; // prevent webkit from resizing text to fit
  -webkit-user-select: none; // prevent copy paste, to allow, change 'none' to 'text'
  user-select: none; // same as above
  font-family: 'HelveticaNeue-Light', 'HelveticaNeue', Helvetica, Arial, sans-serif;
  font-size: 12px;
  height: 100%;
  margin: 0px;
  // Padding to avoid the "unsafe" areas behind notches in the screen
  padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px);
  width: 100%;
}

// Portrait layout (default)
.container {}

// Landscape layout (with min-width)
@media screen and (min-aspect-ratio: 1/1) and (min-width:400px) {
    .container {}
}

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 Apache Cordova
  • rmp/dist/rmp.min.js Radiant Media Player self-hosted core JavaScript file
  • js/index.js with our logic to start the application and the player

www/js/index.js

document.addEventListener('deviceready', onDeviceReady, false);
function onDeviceReady() {
  const src = {
    hls: 'https://your-hls-stream.m3u8'
  };
  const settings = {
    licenseKey: 'your-license-key',
    src: src,
    autoHeightMode: true,
    // we tell the player where to look for the self-hosted player files
    // not needed if you use our cloud-player
    pathToRmpFiles: 'rmp/',
    // if we need ads
    // ads: true,
    // rmp-vast is generally preferred in Apache Cordova apps to display ads
    // adParser: 'rmp-vast',
    // adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',
    // You can turn this off if you do not want automatic fullscreen on landscape rotate
    automaticFullscreenOnLandscape: true,
    contentMetadata: {
      poster: [
        'https://www.radiantmediaplayer.com/images/poster-rmp-demo.jpg'
      ]
    }
  };
  const elementID = 'rmp';
  const rmp = new RadiantMP(elementID);
  rmp.init(settings);
}

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 transferred to our test Android device. With proper configuration we can do the same for iOS.

iOS specific considerations

  • Developing, testing and building your app on iOS requires a macOS device with latest Xcode installed. Refer to this Apache Cordova documentation article for more information.
  • iOS developers need to generate a provisioning profile to code sign their apps for testing.
  • You need to configure your Apache Cordova application to play media content inline for the player to work as expected. This can be achieved by adding to your Apache Cordova root config.xml file:
    <preference name="AllowInlineMediaPlayback" value="true" />
    You may also add the following for autoplay and AirPlay to work as intended:
    <preference name="MediaPlaybackAllowsAirPlay" value="true" />
    <preference name="MediaPlaybackRequiresUserAction" value="true" />

We do support displaying VAST video advertisement in an Android, iOS or iPadOS mobile app built with Apache Cordova. It should be noted that since the HTML5 Google IMA SDK is not officially supported in an iOS or Android WebView, the preferred solution is to use our VAST parser rmp-vast. See this section for more information on limitations when using the Google IMA HTML5 SDK in a WebView mobile app. The VAST parser can be selected with player setting adParser set to 'rmp-vast' (or 'ima' but not recommended).

DRM specific considerations

It is perfectly possible to play DRM encrypted content in a WebView managed by Apache Cordova.

For iOS, FairPlay DRM streaming should work out of the box with Apache Cordova default configuration, just add your FairPlay player code to your JavaScript.

For Android the Widevine CDM needed to playback encrypted content is present in the Android System WebView.

Playback of DRM content on Android however requires a secure context, otherwise the player will throw a 308 error. You can inspect the WebView of your Apache Cordova project with Chrome dev tools when running on an actual Android device. Then you can run in the console:

window.origin

It should return something like https://localhost. If it returns an IP address or a non-HTTPS URI then you need to adjust your project to run in a secure context. More information on the subject can be found here.

DRM content generally does NOT playback on Android emulators - test on an actual device to make sure your DRM content can play as expected.

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.