license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
This guide shows you how to set up an SDK environment to target applications for the BlackBerry platform prior to version 10. If you want to target the most recent version, see the BlackBerry 10 Platform Guide. See the following for more detailed platform-specific information:
The command-line tools above refer to versions prior to Cordova 3.0. See The Cordova Command-line Interface for information about the current interface.
This version of BlackBerry is not supported by the cordova utility described in The Command-line Interface, but by a separate set of command-line tools. Download the Cordova distribution from cordova.apache.org.
Cordova for BlackBerry relies on the BlackBerry WebWorks framework, which is available for Windows XP (32-bit), Windows 7 (32-bit and 64-bit), and Mac (OS X 10.6.4+). WebWorks applications can only be deployed on the following BlackBerry platforms:
WebWorks requires the Java Development Kit (JDK). For Windows, use the 32-bit version of Oracle JDK. Java in installed by default on Mac OS X up to version 10.7, which requires a separate installation. It also requires Apache Ant, which on Mac is part of the Java installation. The Windows version is available from ant.apache.org.
Download and install the appropriate WebWorks SDK for your development. BlackBerry PlayBook and BlackBerry Smartphone WebWorks SDKs can be downloaded from the following locations.
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.
Download and extract the latest copy of Cordova.
blackberry directory.example folder contains a complete Cordova project. Copy the example folder to another location on your computer.BlackBerry 10 (QNX)
qnx.bbwp.dir=C:\\Program Files (x86)\\Research In Motion\\BlackBerry 10 WebWorks SDK 1.0.2.9Along with the SDK, you also need to register for a code signing key and debug token. The signing key allows you to distribute apps through BlackBerry World. The debug token allows you to test unsigned apps on a BlackBerry emulator or device. You do not need to create and install the debug token yourself; if you supply the keystore password, the build script creates and installs the debug token for you. To set up the signing key, go to the Blackberry website to obtain it, making sure to retain the password you specify. Then run the blackberry-signer utility that is included with the SDK. Consult the following for more information:
Build the Cordova sample project by typing ./cordova/build <target> in your command prompt while you are in your project's directory. Replace <target> with either qnx playbook or blackberry. For example...
Open up a command-line terminal. From the directory where you extracted Cordova, navigate to the blackberry subdirectory.
Copy the blackberry directory's example subdirectory to another location on your computer and navigate there.
Edit the project.properties file to specify the WebWorks SDK you are using. For example, here are the respective settings for BlackBerry PlayBook or BlackBerry Smartphone (OS5-7):
playbook.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\\bbwp blackberry.bbwp.dir=C:\\Program Files\\Research In Motion\\BlackBerry WebWorks Packager
These correspond to parameters you specify when building your project. The first time you run these commands, they generate a “Hello World” application:
cordova/build playbook cordova/build blackberry
BlackBerry smartphone emulators are only available on Windows. BlackBerry PlayBook emulators require VMWare Player (Windows) or VMWare Fusion (Mac OS X). The WebWorks SDK provides a default emulator, but additional emulators are available through BlackBerry.
While in your project directory, in command prompt type ./cordova/run <target>. Replace <target> with either qnx, playbook, or blackberry. Note, for BlackBerry 10 and PlayBook, the emulator virtual image must already be started. For example...
For BlackBerry Playbook, edit the project.properties file to customize the playbook.sim.ip and playbook.sim.password properties. The emulator's IP address is available through the Settings application on the home screen. Enable the Security and Privacy → Development Mode option to display the address. The password can also be set in the Security and Privacy tab.
For BlackBerry Smartphone, edit the project.properties file to customize the blackberry.sim.dir and blackberry.sim.bin properties. You need to escape path delimiters when specifying directory paths on Windows, for example: C:\\Program Files\\BlackBerry\\Simulator.
Once the emulator is installed and running, run either of the following to install an application to the home screen:
cordova/run playbook cordova/run blackberry
If you are prompted whether a device is connected to your computer, answer no.
NOTE: On BlackBerry OS 5, the application is installed in the Downloads folder.
To deploy your app to a device, it must be connected, and you must be registered for code signing keys as described above. Also, to deploy apps on BlackBerry PlayBook, the Settings → Security → Development Mode option must be enabled.
On Blackberry PlayBook, edit the project.properties file and modify the following to reflect the device's IP and password as descibed above, along with the signing key password you set up:
While in your project directory, in command prompt type ./cordova/run <target>. Replace <target> with either qnx, playbook, or blackberry. For example...
On BlackBerry Smartphone (OS5-7), specify the blackberry.sigtool.password property as the signing key password.
Then from the project's directory, run either of the commands you would to view the app in an emulator:
cordova/run playbook cordova/run blackberry
If you are prompted whether a device is connected to your computer, answer yes.
NOTE: On BlackBerry OS 5, the application is installed in the Downloads folder.
The following articles may help resolve common problems when developing applications built for the BlackBerry WebWorks framework: