Testing Cordova Apps on Your BlackBerry 10 Phone

Apache Cordova, better known as PhoneGap, Adobe’s commercialized edition of Cordova, allows developers to create apps for a variety of platforms using a single HTML5, CSS and JavaScript code base. This approach of cross-platform development works for all established mobile platforms and doesn’t stop at exotic ones, such as BlackBerry 10.

Despite its infinitesimal market share, there are valid reasons to target the BlackBerry 10 platform. Adding BlackBerry 10 as a target platform to a Cordova-based project is as easy as running the cordova platform add blackberry10 command on your terminal. However, if you try to deploy your app to the device and run cordova run blackberry10, you might stumble upon the following error message:

blackberry-nativepackager cannot be found on the path. Aborting.

It seems as if we are missing the native platform SDK here. In this article, I want to show you which steps are required in order to successfully run and debug your Cordova-based app on your BlackBerry 10 phone. Please note that I’m using OS X, so the exact steps may and will differ on other platforms.

Note: macOS 10.12 Sierra does not support the BlackBerry Link drivers required to connect to your device.

Preparing Your Device

Before being able to deploy and debug apps on your BlackBerry 10 phone, you first have to enable the development mode. In order to do so, open the Settings app and navigate to Security and Privacy > Development Mode. Next, toggle the Development Mode switch and enter your device password. Please note that the development mode will be disabled after a device restart or ten days after activation.

Note: If you have enabled USB Mass Storage mode, you first have to disable it in the Storage and Access section of the Settings app.

Downloading the SDK

Next, visit the downloads page of the Native SDK for BlackBerry 10. BlackBerry offers an Eclipse-based IDE called Momentics, available for Windows, OS X and Linux. This download already includes the Native SDK for BlackBerry 10.

BlackBerry Deployment Setup Wizard

After installing Momentics, launch it and open the Preferences menu. Select the BlackBerry node from the settings tree and click the BlackBerry Deployment Setup Wizard link. The wizard will guide you through all required steps, including:

  • Device Setup
  • Signing Registration
  • Debug Tokens

This process is quite complex (make sure you remember all passwords and keyphrases), but after the wizard is completed, you are almost ready to go.

Setting up the Terminal Environment

The obvious reason of the error message above is that the blackberry-nativepackager command is missing from the PATH environment variable. Fortunately, the application package of Momentics contains a shell script adding all required dependencies to according environment variables. Please note that the following instructions will differ depending on your operating system and SDK version. Momentics allows you to update the SDK version using the Help > Update API levels… menu option.

  1. Navigate to the application package of Momentics, e.g. cd /Applications/Momentics.app (this step is required, as the shell script makes use of relative paths)
  2. Load the shell script matching the target SDK version into your current terminal, e.g. source ./bbndk-env_10_3_1_995.sh
  3. Switch back to your Cordova project and run the cordova run blackberry10 command
  4. Done!

Note: The environment variables will only be set for the terminal session’s lifetime.

Cordova app up and running on BlackBerry 10

Debugging

Debugging your app on BlackBerry 10 is also quite easy. When running your app using a debug token on your BlackBerry 10 phone, a web server providing the Web Inspector will automatically spawn at a port starting from 1337. The Web Inspector resembles the developer tools known from Google Chrome. Simply open http://<blackberry-ip-adress>:1337 and inspect your app as you would do in your browser.

Web Inspector

Release Deployment

Cordova creates unsigned BlackBerry 10 app packages by default. In order to create release deployments that are ready for distribution via BlackBerry World, run:

cordova build --release --keystorepass <signing password>

If you are interested in “real” cross-platform development, you might want to check out the BoardZ cross-platform demo which in addition can also be packaged as a native desktop application.

Published by

Christian Liebel

Hey there! I am Christian Liebel from Leimersheim, Germany. I’m working at Thinktecture in Karlsruhe. Angular, cross-platform development using Cordova and Electron, Gulp, .NET and Node.js are our day-to-day business. Feel free to contact me anytime.