BlackBerry Platform Guide
Cordova for BlackBerry makes use of the BlackBerry WebWorks framework. BlackBerry WebWorks tooling is available for Windows or Mac environments.
WebWorks applications can ONLY be deployed to the following BlackBerry platforms:
- BlackBerry OS 5.0 and higher
- BlackBerry PlayBook
- BlackBerry 10 (QNX)
1. Requirements
- Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+
- Java Development Kit (JDK)
- Windows: Oracle JDK (32-Bit Version)
- Mac OS X: Versions prior to Mac OS X 10.7 provided Java by default. OS X 10.7+ requires installation of Java.
- Apache Ant
- Windows: Apache Ant.
- Mac OS X: Apache Ant is bundled with Java install.
2. Install the WebWorks SDK
Download and install the appropriate WebWorks SDKs for your development. BlackBerry 10, BlackBerry PlayBook, and BlackBerry Smartphone WebWorks SDKs can all be downloaded from the following locations. Please note that BlackBerry PlayBook development requires the Adobe Air SDK as well.
- [BlackBerry 10 (QNX) SDK] (https://developer.blackberry.com/html5/download/#blackberry10)
- [BlackBerry PlayBook SDK] (https://developer.blackberry.com/html5/download/#playbook) & Adobe Air SDK
- [BlackBerry Smartphones SDK] (https://developer.blackberry.com/html5/download/#smartphones)
3. Register for Signing Keys
If you wish to publish your application on BlackBerry App World, or deploy on an actual device you’ll need to register for a set of free Code Signing Keys.
To register for Signing Keys visit, and complete the BlackBerry Keys Order Form.
Once you receive your Signing Keys, they'll need to be setup. To learn how to setup your Signing Keys visit the BlackBerry HTML5/WebWorks website.
4. Install Cordova
Download and extract the latest copy of PhoneGap.
5. Set up New Project
- Open up a command prompt/terminal and navigate to where you extracted Cordova.
- There is a directory for each platform that Cordova supports. CD into the blackberry directory.
- The blackberry directory contains several directories. The
examplefolder contains a complete Cordova project. Copy theexamplefolder to another location on your computer. - Change to the newly created directory.
- Open up the project.properties file with your favorite editor and edit the entries for the WebWorks SDKs you are using. For example...
BlackBerry 10 (QNX)
- qnx.bbwp.dir=C:\\Program Files (x86)\\Research In Motion\\BlackBerry 10 WebWorks SDK 1.0.2.9
BlackBerry PlayBook
- playbook.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\\bbwp
BlackBerry Smartphone (OS5-7)
- blackberry.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks Packager
6. Hello World
Build the Cordova sample project by typing ./cordova/build <target> in your command prompt/terminal while you are in your project's directory. Replace <target> with either qnx playbook or blackberry. For example...
BlackBerry 10 (QNX)
- ./cordova/build qnx
BlackBerry PlayBook
- ./cordova/build playbook
BlackBerry Smartphone (OS5-7)
- ./cordova/build blackberry
7A. Deploy to Simulator
BlackBerry smartphone simulators are only available on Windows. BlackBerry 10, and PlayBook simulators require VMWare Player (Windows) or VMWare Fusion (Mac OS X). The WebWorks SDK provides a default simulator. Additional simulators are available.
For instructions on installing simulators, please visit the following link(s): - BlackBerry 10 - BlackBerry PlayBook - BlackBerry Smartphone
- Open the project.properties file with your favorite editor and customize the following properties.
BlackBerry 10
- qnx.sim.ip
- qnx.sim.password
- NOTE: IP address of simulator obtained when placing the simulator in developer mode through simulator security settings. Simulator password can be set through simulator security settings.
Playbook
- playbook.sim.ip :
- playbook.sim.password
- NOTE: IP address of simulator obtained when placing the simulator in developer mode through simulator security settings. Simulator password can be set through simulator security settings.
Smartphone (Optional)
- blackberry.sim.dir
- blackberry.sim.bin
- NOTE: On windows file separator '\' must be escaped when specifying directories. For example C:\\Program Files\\BlackBerry\\Simulator.
While in your project directory, in command prompt/terminal type ./cordova/run <target>. Replace <target> with either qnx, playbook, or blackberry. Note, for BlackBerry 10 and PlayBook, the simulator virtual image must already be started. For example...
BlackBerry 10 (QNX)
- ./cordova/run qnx
BlackBerry PlayBook
- ./cordova/run playbook
BlackBerry Smartphone (OS5-7)
- ./cordova/run blackberry
When prompted Do you have a BlackBerry device connected to your computer? (y/n), answer n.
The application is installed to the simulator's home screen. Note that on BlackBerry OS 5, it is installed in the Downloads folder.
7B. Deploy to Device (Windows and Mac)
To deploy your app to a device you must have registered for, and setup BlackBerry Code Signing Keys. See section 3 for details. Also, to deploy apps on BlackBerry 10 or PlayBook, the device must be set to Development Mode which can be enabled from the Settings → Security menu.
- Open the project.properties file with your favorite editor and customize the following properties:
BlackBerry 10 (QNX)
- qnx.sigtool.password
- qnx.device.ip
- qnx.device.password
BlackBerry PlayBook
- playbook.sigtool.csk.password
- playbook.sigtool.p12.password
- playbook.device.ip
- playbook.device.password
BlackBerry Smartphone (OS5-7)
- Smartphone (Optional)
- blackberry.sigtool.password
While in your project directory, in command prompt/terminal type ./cordova/run <target>. Replace <target> with either qnx, playbook, or blackberry. For example...
BlackBerry 10 (QNX)
- ./cordova/run qnx
BlackBerry PlayBook
- ./cordova/run playbook
BlackBerry Smartphone (OS5-7)
- ./cordova/run blackberry
When prompted Do you have a BlackBerry device connected to your computer? (y/n), answer y.
The application is installed to the device's home screen. Note, on BlackBerry OS 5 the application is installed in the Downloads folder.
Additional Information
The following articles provide help to issues you may encounter when developing a Cordova application which is based on the BlackBerry WebWorks framework