February 7, 2012 19

Getting started with PhoneGap on BlackBerry PlayBook


Playbook Screenshot

PhoneGap is a great tool for creating cross platform mobile apps. Whilst the documentation for deploying to iOS and Android is really thorough, I’ve found the BlackBerry PlayBook guide, especially when using a Mac, to be quite sparse.

Here are the steps I took to setup a development environment for both the simulator and an actual device.#Prerequisites

Before you get started you need to download the following:

Note: When asked where to install the WebWorks SDK I chose /Developer/PlayBookSDK. You will need this path later so if you install somewhere different then make a note of it.

Build & run PhoneGap HelloWorld

Once the WebWorks SDK is installed and PhoneGap has been downloaded, you will need to:

Copy the sample application

Copy the folder lib/blackberry from the PhoneGap release to a new location

$ cp -ap ./lib/blackberry /Developer/Apps/PlayBook/helloworld

Then change your working directory to the sample folder

$ cd ./sample

Update the properties file

Various parameters need to be set within the project.properties file, to enable building and deployment of WebWorks apps. Firstly you need to provide the location of the BlackBerry WebWorks Packager (aka bbwp). Its important that you use the directory to which you installed the SDK, not the path to the bbwp directory itself (use the directory one level higher). For my setup the correct path was:


Install the PlayBook Simulator

The PlayBook simulator is bundled with the SDK download and can be run from within VMWare Fusion. Open Fusion and import the following file:


Once imported, run the simulator.

Setup the Simulator for Development

To setup the simulator for development work you will need to do the following:

  1. Tap on the Settings icon top right of the screen
  2. Select the ‘Security’ tab
  3. Select ‘Development Mode’
  4. Enable the ‘Use Development Mode’ toggle

    Development Mode

  5. Return to the homescreen and a new icon should have appeared in the menubar

  6. Tap the new icon and make a note of the IP address

    Obtain IP

Now update you project.properties file with the simulators IP address:


You’re now ready to deploy the app to the simulator:

ant playbook load-simulator

Depending on the file permissions of your SDK folder you may need to run the ant command as sudo. Once the build has completed the Hello World app should launch in the simulator.

Setup a Device for Development

Follow steps 1-6 from the above simulator instructions on the device to enable Development Mode and obtain the devices IP address. Add the IP address to your project.properties.


Signing certificates are required to test applications on real hardware. These can be applied for with the BlackBerry Code Signing Keys Order Form. I found the turn-around to be very quick, with the keys arriving within a couple of hours.

Once your keys arrive (via email) then follow the instructions from the BlackBerry site on how to install them. Note that the “password” you choose will need to be written into a plain text file so don’t pick anything you use for anything else!

You then just need to update your project.properties file once again and add the passwords you created in the previous step:


You should now be able to deploy to the device using the deploy script:

ant playbook load-device

Enabling the Remote Inspector

At the time of writing the PlayBook is the only device to ship with remote WebKit debugging. This is one area that the PlayBook really excels and makes creating PhoneGap based apps much easier when compared to other platforms such as iOS & Android.

To enable this functionality in your PhoneGap/WebWorks app you need to do the following steps.

From either the simulator or device:

Ensure a password is set

  • Tap on the Settings icon top right of the screen
  • Select the ‘Security’ tab
  • Select ‘Password’
  • Enable the ‘Use Password’ toggle & provide a password

Add the password to your properties file:

Add the following to you project.properties file:


or for simulator:


Update the build settings

Add a flag to the playbook.xml file. Find <!-- BBWP MACRO --> and add <arg value="-d" /> to the two <exec> nodes in following block:

<exec executable="${bbwp}">
    <arg file="${build.dir}/${cod.name}.zip" />
    <arg value="-gcsk" />
    <arg value="${properties.playbook.sigtool.csk.password}" />
    <arg value="-gp12" />
    <arg value="${properties.playbook.sigtool.p12.password}" />
    <arg value="-o" />
    <arg file="${build.dir}" />
    <arg value="-buildId" />
    <arg value="${build.number}" />
    <arg value="-d" />


<exec executable="${bbwp}">
    <arg file="${build.dir}/${cod.name}.zip" />
    <arg value="-o" />
    <arg file="${build.dir}" />
    <arg value="-buildId" />
    <arg value="${build.number}" />
    <arg value="-d" />

This will enable the Web Inspector for your WebWorks/PhoneGap app (be sure to remove this when it comes time to distribute).

Load a browser on your desktop/laptop

Visit the IP address of your device/simulator using port 1337, e.g.

You should now be able to debug your application using the familiar WebKit inspector, including JavaScript breakpoints, console access and CSS manipulations.

I wrote this guide partly as a resource for myself after working on porting the Rareloop Mobile Data Collection framework to work on the Playbook. If you find any in-accuracies or improvements or would like to discuss our mobile data collection platform some more, just give me a shout in the comments or via the Rareloop website.

  • Gordon

    Thats a great post on developing for Blackberry using Phonegap. I wish there were more posts like this for developing on a PC. The Android related tutorials are great as you said but the ones for Blackberry are poor or out of date.

  • http://www.joelambert.co.uk Joe Lambert

    Thanks Gordon, I wrote this up mainly as a reference for myself. As you mention the docs are not as strong (or easy to find) for BB dev as other platforms.

    In retrospect there really aren’t too many steps requires, it just took me quite a bit of experimenting to get to the correct process! Hopefully the above is helpful and saves you some time.

  • Femolinari

    Excellent post. I was hoping to get some help with these 2 problems.It always fails while trying to  upload an image o the server or copying it to a different folder. I’m following the instructions according to phonegap API. I’m wondering if I need to add something to the config.xml file lke a permission is missing or something.The same code works fine for IOS and Android.Thanks,

  • http://www.joelambert.co.uk Joe Lambert

    I’ve asked about and as yet have no concrete answers. 

    I will however be porting an existing PhoneGap app that uses the API’s you mention to Playbook in the next few weeks so if I figure anything out or hear back from the Adobe guys I’ll add a comment.

  • Femolinari

    I found the answer while looking for their road map. It’s not implemented yet for playbook. don’t know when they’re gonna do it.

  • guest

    Excellent tut.  Phonegap should have this on their site!  I was having some signing issues till I found this link – for anyone who is stuck on that:   http://supportforums.blackberry.com/t5/Testing-and-Deployment/BlackBerry-Tablet-OS-Graphical-Aid/ta-p/1207067?CPID=TWDResources&Date=11912

  • http://www.joelambert.co.uk Joe Lambert

    Glad it was useful!

  • Ronald Valencia

    Hi Joe i was wondering if you can help me out i have been trying to register the csj files that rim sent me but in the mac terminal i keep getting an error.

    this is what Im typing into terminal im not even sure if its right 

    Ronald-Valencias-MacBook:~ Ron$ /Users/Ron/playbooksdk/bbwp/blackberry-tablet-sdk/bin/blackberry-signer -register -storepass mypassgoeshere -csjpin mypingoeshere client-RDK-##########.csj client-PBDT-#########.csj

    then i get this Error: Unable to open CSJ file: it shows both CSJ files what am i doing wrong?? I have both csj files in the bin i made my own storepass(in the terminal i just made something up not sure if im supposed to do that)  and i used the pin that i made when i signed up with RIM thank you

  • Ronald Valencia

    i figured it out by using this program. RIM should be adding this to their tutorial on how to get things started.

    its has everything in one location took like 5 minutes to get everything going.

    here it is everyone .


  • http://www.joelambert.co.uk Joe Lambert

    Thanks for posting the fix Ronald, hopefully this will help others with the same issue.

  • Ishan

    Hi joe can u pls help me with an issue i have’nt been able to figure out, i have a sencha and phonegap based bb playbook application. My html contents do not appear on the sencha panels nor on the index.html page. it wud be really kind of u if u could find be reason why does it happen so???? i have a presentation coming up !! Thanks in advance :)

  • http://www.joelambert.co.uk Joe Lambert

    Hi Ishan,

    I’m afraid I’m a bit snowed under at the moment, but heres some things to test:

    • Does your app work as expected in a desktop browser, e.g. Chrome?
    • Have you downloaded the most recent version of PhoneGap/Cordova?
    • Are you running the latest PlayBook OS and have the latest SDK?

    It might be worth getting in contact with the BlackBerry developer relations guys on Twitter, they’re really responsive and very helpful: @BlackBerryDev:twitter 

  • Sohilkumar Bhavsar

    Hi Joe,

    Did you know how to solve memory issue with Google Map on BlackBerry Phones?

    Or Did you had seen any Phonegap app which will work on Blackberry Devices?

    We have a good app which will work on Playbook but not on devices as it will create low memory error on device.


    Sohil Bhavsar.

  • Ishan

    Hi joe, Firstly sorry for the late reply was shifted to anoder project now i am back on BB development. 1) Yes the applicatikon works fine on the Chrome Browser 2) i am using the phonegap/cordova 1.6.1 version 3) the Sdk and os version is as follows BlackBerry WebWorks SDK for TabletOS

  • http://www.joelambert.co.uk Joe Lambert

    Sorry, I haven’t much experience with working with PhoneGap on BB Phones.

  • http://www.joelambert.co.uk Joe Lambert

    It sounds like you’re getting a JavaScript error which is causing the app the fall over before the DOM has loaded.

    Have you tried attaching to the remote web inspector to see if you get any console errors? Only other thing I can think (and this is a pain!) is to start adding some alerts into you code to try find how far through the app is getting before falling over?

  • Pingback: PhoneGap on PlayBook

  • http://www.facebook.com/people/Sid-Labs/100000804868370 Sid Labs


    Can you please tell how to add a bookmark of an App on Playbook so that it could be started from Home Screen? Also I don’t want internet to be On all the time when running the app.

    Also, do I need an IP to access the App all the time?

  • http://www.joelambert.co.uk Joe Lambert

    You shouldn’t need to add a bookmark as once you compile your PhoneGap/WebWorks app it will create an icon on the homescreen from which you can launch your app.

    As for the IP address, you only need this to deploy a new build of your applications. Once its installed on your device you should be able to launch your app (even with Developer Mode disabled) from the icon on the homescreen.