Welcome!

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

 

 

Index

Upgrade Cordova and WebWorks

Update Plugins

Install Android SDK, and Android Studio

Install SDK Packages

Config.xml

Splash Screens
Plugins and APIs

Testing Your App

Building for Release

Test Case

API Mapping

Troubleshooting

 

 

 

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

 

cordova-update.jpg

 

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

$ cordova platform update blackberry10

webworks-update.jpg 

 

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

 

 

Config.xml

 

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.

 

config-platforms.jpg

 

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

 

config-platform-more.jpg

 

 

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.

 

code-bb10-camera.jpg

 

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:

 

camera-code.jpg

 

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

 

cordova-update.jpg

 

2.   Update BlackBerry WebWorks:

      $ cordova platform update blackberry10

 

webworks-update.jpg

 

3.   Add the Android platform:

      $ cordova platform add android

 

platform-add-android.jpg

 

4.   Run the app:

      $ cordova run android –device

 

run.jpg

 

 

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.

 

COM.BLACKBERRY.APP

CORDOVA-PLUGIN-APPINFO

COM.BLACKBERRY.CONNECTION

CORDOVA-CONNECTIVITY-MONITOR

COM.BLACKBERRY.INVOKE.CARD

CORDOVA-WEBINTENT

COM.BLACKBERRY.INVOKE

CORDOVA-WEBINTENT

COM.BLACKBERRY.INVOKED

CORDOVA-WEBINTENT

COM.BLACKBERRY.IO.FILETRANSFER

CORDOVA-PLUGIN-FILETRANSFER

COM.BLACKBERRY.IO

CORDOVA-PLUGIN-FILE

COM.BLACKBERRY.NOTIFICATION

CORDOVA-PLUGIN-LOCAL-NOTIFICATIONS

COM.BLACKBERRY.PAYMENT

CORDOVA-PLUGIN-GOOGLE-PAYMENTS

COM.BLACKBERRY.PIM.CALENDAR

CORDOVA-PLUGIN-CALENDAR

COM.BLACKBERRY.PIM.CONTACTS

CORDOVA-PLUGIN-CONTACTS

COM.BLACKBERRY.UI.TOAST

CORDOVA-PLUGIN-DIALOGS

COM.BLACKBERRY.UI.DIALOG

CORDOVA-PLUGIN-DIALOGS

COM.BLACKBERRY.SENSORS

CORDOVA-PLUGIN-DEVICE-MOTION,

CORDOVA-PLUGIN-DEVICE-ORIENTATION,

CORDOVA-PLUGIN-PROXIMITY,

CORDOVA-PLUGIN-MAGNETOMETER,

CORDOVA-PLUGIN-GYROSCOPE

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Troubleshooting

 

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

 

cordova-requirements.jpg 

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

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