Porting your existing PhoneGap application to BlackBerry 10

by BlackBerry Development Advisor on ‎01-10-2013 11:43 AM - edited on ‎10-21-2013 04:33 PM by BlackBerry Development Advisor (13,187 Views)

Porting existing PhoneGap apps to BlackBerry 10

If you haven’t yet heard, as of version 2.2, you can now package BlackBerry® 10 apps with PhoneGap™.  This quick PhoneGap porting guide was written to help you port existing BlackBerry® WebWorks™ PhoneGap apps over to the BlackBerry 10 platform.  The whole process is really simple, but there are a few things you need keep in mind as you begin repackaging your apps for BlackBerry 10.

 

This guide is not in its final form, and will very likely be evolving as time goes on and more BlackBerry 10 support is added.

 

Is this guide for me?

This guide assumes that you are looking to port an existing BlackBerry WebWorks app, written in PhoneGap to BlackBerry 10.  If you're new to PhoneGap development, there is a complete Getting Started Guide available that will take you though the whole setup process and may be better suited for you.

 

Before you begin

Before you dive in and start porting your app, there are a couple things you'll want to do first.

 

Download the SDK & simulator

The BlackBerry 10 WebWorks SDK is super lightweight, running in under 9mb in size.  Download and install it for Windows or Mac.  If Linux is your thing, we’ve got you covered there too. Thanks to the efforts of the community, the SDK is also available for Linux.

 

Windows & Mac: https://developer.blackberry.com/html5/download

Linux: https://github.com/badtoyz/BB10-WebWorks-SDK-Linux

  

Register for signing keys

Although you probably have signing keys for BlackBerry 7 (and lower), you’ll need the register for a new set of BlackBerry 10 signing keys.

 

BlackBerry signing keys: https://www.blackberry.com/SignedKeys

 

For a step-by-step guide on how to register your keys, visit the Setup for signing BlackBerry 10 Apps page on our HTML5 Microsite. 

 

 

What's new in BlackBerry 10

While the porting process is pretty easy, there are a number of changes that you need to take into consideration when repackaging your application.  

 

Scaling / viewport

With the increased screen density of the BlackBerry 10 Dev Alpha device, content which looks fine on an earlier device may not be the proper size on a new one.  If you're following our best practices, you'll want to make sure that your content scales appropriately for the given screen resolution.

 

BlackBerry 10

  • Screen resolution: 1280 x 768 (Dev Alpha Device)
  • Pixel density: 355 dpi

To set the viewport for a BlackBerry 10 device, see How to set up the viewport for a BlackBerry WebWorks application for BlackBerry 10.

 

Home screen icons

Your home screen icon is also affected by the richer screen density of the BlackBerry 10 Dev Alpha device, and may need to be resized in order to look as great as possible on the new devices.

 

BlackBerry 10

  • Icon size: 114 x 114
  • Larger icons will be scaled down automatically

Your application icon is the first thing the user comes across.  A poorly designed icon on the home screen sticks out like a sore thumb. It's highly recommended that you check out our UI Guidlines relating to your application's icon to make it look amazing.

 

Config.xml

There are also some small changes you'll need to make in your apps config.xml file.  Take a look at the sample configuration document for BlackBerry 10. The widget element is quite different now, as well as the syntax for requesting certain permissions.  A full list of config.xml elements is available here.

 

WebWorks "ready" event

One of the biggest differences when porting your app over to BlackBerry 10 is that before calling any native BlackBerry WebWorks APIs, you have to wait for the environment to be “ready”.  

 

BlackBerry WebWorks supplies an event for this.  Before trying to access any of the native APIs, you’ll want to listen for this event, and then call any of the APIs you need.

 

// register ready event after window has loaded 
window.addEventListener("load", function (e) {
document.addEventListener("webworksready", function() {
// initialize your app, call api's here
console.log("webworks is ready!”) }, false);

 

Refer to Getting Started with BlackBerry 10 for more information on the webworksready event.

 

 

Getting started with PhoneGap

Now that you're ready to begin the build process, here are a few things you'll need to know about PhoneGap and BlackBerry 10.

 

API support

While BlackBerry 10 is still in beta, the support for PhoneGap APIs is getting better in each release.  We’re working closely with PhoneGap and Apache Cordova™ to better align our APIs with theirs to make it easier for developers to work with our SDK, and/or PhoneGap’s.

 

As of PhoneGap v2.2 the following APIs are supported on BlackBerry 10:

  • Accelerometer
  • Camera
  • Geolocation
  • Network
  • Notification Alerts
  • Storage
  • Media

Is there an API missing from this list that you need? Feel free to reach out to me on Twitter and let me know!

 

Download PhoneGap

Make sure you have the latest version of PhoneGap before you start repackaging.  As of version 2.2, BlackBerry 10 support is included.  You can download the latest version of PhoneGap here.

 

Create a new project

Although you may already have a project created, it's probably easiest to create a new project with the latest PhoneGap release, and then copy your resources over to it.  This will make sure that you have all the new files needed to run your app on BlackBerry 10.

 

To create your new project

  • Extract the PhoneGap archive
  • Navigate to the lib/BlackBerry folder
  • Copy the sample folder

This will be your new, blank project. Now you can begin setting the project up, and are almost done!

 

Set up your project

You'll need to set up the project's properties file so that it knows where to look for the BlackBerry 10 WebWorks SDK, as well as other information needed for the build process.

 

To setup your project, first open the project.properties file in a text editor and make the following edits:

 

Set the path to the SDK

This is the full path to the BlackBerry 10 WebWorks SDK.  Note the double-slashes "\\".

 

qnx.bbwp.dir=C:\\Program Files (x86)\\Research In Motion\\BlackBerry 10 WebWorks SDK 1.0.4.5

 

Set the signing password

The password created when you setup your Signing Keys.  This is needed for signing builds.

 

qnx.sigtool.password = “abcd123456”

 

Set your device IP address and password

PhoneGap can deploy your app to this device automatically.

 

qnx.device.ip = “192.168.0.120”
qnx.device.password = “abcd123456”

 

Set the simulator IP address and password

If you don't have a BlackBerry 10 Dev Alpha device, you can also test on the BlackBerry 10 Device Simulator.  

 

qnx.simulator.ip = “192.168.0.120”
qnx.simulator.password = “abcd123456”

 

Building & deploying

Now that your app is setup, resources are copied over, and you're ready to start making money, you can build your app with PhoneGap.

 

Building for BlackBerry 10 is slightly different.  Instead of using "blackberry" as the target, you use "qnx".  Here are a couple examples.

 

Build your project

This command will build, and sign your application.

 

ant qnx build

 

Deploy to the device

Load your app onto the device

 

ant qnx load-device

  

Web Inspector

If you don’t already use Web Inspector to debug your apps, DO IT!  It’ll save you so much time and effort porting your app, and is well worth taking a minute to enable it.  In a nutshell, Web Inspector lets you see what’s happening in your app, while it’s happening in real time on the device or simulator.  You can check the console for errors, view network activity, add break points to your code, and much more. 

 

For a quick lesson on how to do all of this, visit our Using Web Inspector page. 

 

Enabling Web Inspector

To enable Web Inspector in your PhoneGap project, open up the qnx.xml file in your favourite editor and add <arg value=”-d” /> at line 178.  The final block of code should look like this:

 

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

  

Note: Don’t forget to comment out <arg value=”-d” /> when publishing your app.  Web Inspector should only be enabled during testing and development.

 

 

Other resources

A complete Getting Started Guide is available on GitHub for those who are new to BlackBerry WebWorks and PhoneGap development.

 

Also, I highly recommend you check out How To: Migrate your BlackBerry WebWorks application from BlackBerry Tablet OS to BlackBerry 10 by Adam Stanley.   It focuses specifically on porting existing PlayBook apps, but the lessons learned there may help you out quite a bit.

 

Follow me on Twitter!

If you have any comments, or suggestions about the material in this porting guide, feel free to follow me on Twitter and let me know!