Knowledge Base

INTEGRATION OF BLACKBERRY WITH PHONEGAP

The integration of Blackberry with PhoneGap needed to deploy the cross platform code to run on mobile. The beauty with PhoneGap is that the same code can be executed on different mobile vendor with minimal change. Also it provide the extendibility to invoke the native code by just injecting the device specific code. It is supported by plugin.xml in that we need to inject the native call mechanism.

PhoneGap 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 BlackBerry devices running OS 5.0 and higher or the BlackBerry PlayBook operating system.

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 SDK + PhoneGap

PlayBook development requires the Adobe Air SDK

Download and install one or more of the WebWorks SDKs. Keep note of the install directory.

Smartphone Development: BlackBerry WebWorks Smartphone SDK

PlayBook Development: BlackBerry WebWorks Tablet OS SDK

Download the latest copy of PhoneGap and extract its contents.

3. Setup AppyPie Project

Open up a command prompt/terminal and navigate to where you extracted PhoneGap.

There is a directory for each platform that PhoneGap supports. CD into the blackberry directory.

The blackberry directory contains two directories, sample and www. The sample folder contains a complete PhoneGap project. Copy the sample folder 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 blackberry.bbwp.dir= and/or playbook.bbwp.dir=. Set the value(s) to the directory containing the bbwp binary in the WebWorks SDK(s) installed earlier.

4. AppyPie Application

Build the PhoneGap sample project by typing ant target build in your command prompt/terminal while you are in your project’s directory. Replace target with either blackberry or playbook. Note this is a sample PhoneGap project and not a basic hello world application. The provided index.html in the www contains example usages of many of the PhoneGap API.

5A. Deploy to Simulator

BlackBerry smartphone simulators are only available on Windows. PlayBook simulators require VMWare Player (Windows) or VMWare Fusion (Mac OS X). The WebWorks SDK provides a default simulator. Additional simulators are available.

Open the project.properties file with your favorite editor and customize the following properties.

Smartphone (Optional)

blackberry.sim.dir : Path to directory containing simulator. On windows file separator ” must be escaped ”.

blackberry.sim.bin : Name of the simulator executable in the specified directory.

Playbook

playbook.sim.ip : IP address of simulator obtained when placing the simulator in developer mode through simulator security settings.

playbook.sim.password : Simulator password which can be set through simulator security settings.

While in your project directory, in command prompt/terminal type ant target load-simulator, replace target with either blackberry or playbook. Note, for PlayBook the simulator virtual image must already be started.

The application will be installed in the All Applications section in the simulator. Note, on BlackBerry OS 5 the application is installed in the Downloads folder.

5B. Deploy to Device (Windows and Mac)

Deploying to a device requires signing keys which can be obtained from RIM.

Fill out this form. to request signing keys.

Install the signing keys once they have been received:

Setup Smartphone Signing keys

Setup Tablet Signing keys

Install BlackBerry Desktop Sofware to be able to install a signed application to a smartphone device attached via USB.

Open the project.properties file with your favorite editor and customize the following properties:

Smartphone (Optional)

blackberry.sigtool.password : Password used when code signing keys were registered. If not specified, a prompt will occur.

Playbook (Required)

playbook.sigtool.csk.password : Signing key password.

playbook.sigtool.p12.password : Signing key password.

playbook.device.ip : IP address of device obtained when placing the device in developer mode through device security settings.

playbook.device.password : Device password which is set through device security settings.

While in your project directory, in command prompt/terminal type ant target load-device, replace target with either blackberry or playbook.

The application will be installed in the All Applications section in the device. Note, on BlackBerry OS 5 the application is installed in the Downloads folder.

Author: Amit Kumar

Designation: Technical Team Lead