Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

WebWorks to Android migration guide for Apache Cordova

by BlackBerry Development Advisor on ‎11-06-2015 03:14 PM (1,006 Views)

With the launch of Priv™ by BlackBerry®, you’re likely thinking about porting all of your BlackBerry® 10 WebWorks® and Apache Cordova™ apps to run on Android™. Luckily, porting your apps is much easier than you think!


This document outlines nearly everything I’ve learned about porting an app to Android. Since WebWorks is so tightly aligned with Apache Cordova, you should be able to port your apps to Android with minimal effort.


Note: Much of the information here can be found in the Apache Cordova documentation. If you’re looking for more of a low-level guide, see the Cordova Android Platform Guide




Upgrade Cordova and WebWorks

Update Plugins

Install Android SDK, and Android Studio

Install SDK Packages


Splash Screens
Plugins and APIs

Testing Your App

Building for Release

Test Case

API Mapping





Backup your code!


First and foremost, you should back up your apps. Odds are that everything will go smoothly, but if you do run into issues, you’ll have a clean project to revert back to. Maybe now is a great time to start using GitHub®? J



Upgrade Cordova and WebWorks


If you haven’t done so already, you should update your globally installed version of Cordova and the WebWorks SDK that’s installed in your project. This will make developing in the future much easier.


For additional information, Tim Windsor wrote a great blog post on upgrading your project to Cordova 5.x and WebWorks 3.8. I highly recommend you read it before continuing past this point.


Update Cordova:

$ npm update –g cordova




Update WebWorks (From your project’s root folder):

$ cordova platform update blackberry10



Update Plugins


As of Cordova 5.x, the plugin naming convention has changed for the better. Any old plugins should be replaced with their updated versions. For example:


Old Plugin -> com.blackberry.app

New Plugin -> cordova-plugin-bb-app


A full list of renamed Cordova plugins can be found.



Install the Android SDK, and Android Studio


Now that your project’s running the latest plugin, let’s look at adding the Android platform to the mix.


First, install the Android SDK and its dependencies. I highly recommend doing this by installing Android Studio so you can take advantage of the native tools for debugging, plugin development, etc.



Install SDK Packages


Next, install additional Android SDK packages. Do this by opening the Android SDK Manager.


Depending on which API level you’re targeting (generally 21+), install the corresponding packages. The Android Platform Guide recommends that you install the following:


  • Android 5.1.1 (API 22) platform SDK
  • Android SDK Build-tools 19.1.0 or higher
  • Android Support Repository (Extras)


You’re now ready to add Android to your project by running:

$ cordova platform add android





After adding the Android platform to your project, you may experience build errors surrounding the parsing of the config.xml file. That’s likely because you’re using platform specific properties. That’s okay, but it requires a minor change.


Any platform specific features (features another platform’s packager wouldn’t recognize) need to be wrapped in a <platform></platform> tag.


Refer to the official Cordova Config.xml documentation for in-depth platform specific configurations.




After correcting that your project should build fine. Don’t forget, any Android specific properties need to be isolated as well.



Splash Screens


Configuring Splash Screens is also slightly different for Android and requires you to install the cordova-plugin-splashscreen plugin. Once installed, you can specify your Splash Screens for Android.


$ cordova plugin add cordova-plugin-splashscreen





Plugins and APIs


You’re probably wondering if your app works on Android “out-of-the-box”. In my experience, for the most part, the answer is yes, most likely.


  • If you developed your app using Cordova APIs, and there is nothing exclusive to BlackBerry 10 in your code, you should be able to port it very easily.


  • If your app uses BlackBerry 10 specific, that aren’t available on other platforms, you will need to get more creative. That’s not to say your app can’t be ported, it just means you’ll likely have to make use of some community-developed Cordova Plugins or create your own.


Each platform you target has its own native functionalities unavailable to other platforms, causing porting issues. The best way to avoid these potential road blocks is to use the core Cordova APIs whenever possible.


For example, interacting with the camera:


The Scenario: You have an app that takes a photo and handles the returned captured-image path. You built the app only for BlackBerry 10, and need to make it work on Android now.


Currently your code likely invokes the BlackBerry 10 camera using the BlackBerry specific “invoke” method. The camera card is invoked, and the corresponding callback is fired.




Now, let’s look at how to port this code block so that it runs on both BlackBerry 10 and Android.


  1. Remove the BlackBerry specific API

    $ cordova plugin remove cordova-plugin-bb-camera

  2. Add the Cordova plugin:
    $ cordova plugin add cordova-plugin-camera
  3. Replace the JavaScript for BlackBerry 10 specific API with the Cordova API:




This code now runs on both BlackBerry 10 and Android devices. As you can see, the JavaScript is quite similar to the original in that you call a method which returns the image’s path.



Testing your app


When you’re done modifying the JavaScript, your app should be ready to run. Plug your Android device in to the computer via USB and run the following:


$ cordova run android --device



Building for release


As with BlackBerry 10, your app needs to be signed before releasing it. For an in-depth walkthrough on how to sign an APK, see the official Android docs on Signing Your Application.



Test Case: Cordova Kitchen Sink Sample (BB10 -> Android)


For a demo, let’s use our latest sample app “The Sample to End All Samples”. As I write this, it supports only BlackBerry 10. Pretend it’s an old app, running an out-of-date version of WebWorks and Cordova. Let’s upgrade it so that it runs on Android.


1.   Upgrade Cordova:
      $ npm update –g cordova




2.   Update BlackBerry WebWorks:

      $ cordova platform update blackberry10




3.   Add the Android platform:

      $ cordova platform add android




4.   Run the app:

      $ cordova run android –device





API Mapping


One aspect that can be tricky when porting an app is when platform specific APIs are used. In many cases there are equivalent cross-platform Cordova plugins and I highly recommend using these whenever possible.


Here’s a list of BlackBerry plugins with Cordova equivalents (where applicable). In many cases you can simply use the Cordova API to handle the task on BlackBerry 10 and Android.


For plugins that are not BlackBerry 10 compatible, you’ll likely need to add logic to your app which determines: a) which platform it’s running on, and b) calls the appropriate API.






































































Having issues getting your Android development environment setup? Cordova 5 comes with a new “requirements” flag. By running the command from your projects root folder, Cordova checks each installed platform and lets you know if one of the dependencies is missing.


Check your environment setup:

$ cordova requirements



If you’re still stuck, head on over to the Cordova documentation and see the official Cordova Android Platform Guide.

Users Online
Currently online: 12 members 486 guests
Please welcome our newest community members: