Package and Deploy a BB10 WebWorks Application

December 25th at 12:00am

RIM has greatly improved their WebWorks platform since the last time time I examined it. It's easier than ever to  get an HTML5 application packaged, tested and deployed to a BB10 simulator or test device.

This article walks through the process to get your HTML5 app packaged and ready to debug on a BB 10 Test device. If you only have the simulator VM, just change your target for 'simulator' and everything will hopefully go your way.

References

 

Prerequisites

Before you can get anything building you will need to download, install and do a few things:

  • Sun/Oracle Java. Java 7 works for me.
    • Watch out during the install: They ask you to install either a toolbar or security scan. I just said no
  • VMWare Player
    • You may need to register for a VMWare account to download this
  • BB10 Dev Alpha Simulator VM
    • This will come in handy for actually testing your applications
    • I suggest going this route instead of Ripple since I haven't had much luck with the newer versions of Ripple that run in Chrome. Better to test on a platform that is as close to the real device as possible, anyway. :)
  • BB10 NDK/Cascades
    • This is useful for accelerating the connection of the Dev Alpha device or VM. Easier to create a Debug token here than with the WebWorks SDK
  • BB10 WebWorks SDK
    • This will give you the CLI tools necessary to package, sign and launch your WebWorks applications on your test device / VM.
  • Register for your code signing keys (if you don't already have them) and install them

Setup Debug Tokens and Device connection

Once you have all the pre-requisites installed, it is time to get the NDK connected to your device or simulator. This will facilitate easy creation and management of Debug Tokens. To do this:

  • Plugin your development test device (or power on the VM)
    • Ensure that Development Mode is activated (This can be found under Settings -> Security )
       
  • Launch QNX Momentics
  • Create a workspace
  • Follow the steps in the BlackBerry configuration wizard
    • If this doesn't launch automatically:
      • Go to Window -> Preferences
      • Click on Blackberry 
      • Then click on Blackberry Deployment Setup Wizard
         
    • During this process you will be asked for your code signing keys and connection information to your test device
       

At this point you should have a working connection to the device and an auto-generated debug token. We need to copy the token to the WebWorks SDK directory for it to be usable in debugging webworks apps:

  • Copy your debug token from C:\Users\USERNAME_HERE\AppData\Local\Research In Motion
    • Should be named debugtoken.bar
  • Copy it to C:\Program Files (x86)\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.4.5

config.xml

With the debug token copied to the WebWorks SDK directory you are getting pretty close to actually building your application for testing. Assuming that your HTML5 application works fine, all you need to do is create a config.xml file in the application root folder next to the index.html file.

This configuration XML document contains various information about the application including (but not limited to):

  • Icon File
  • SplashScreen
  • Application Name
  • Application Description
  • Permissions
  • Orientation (Landscape/portrait)

    For more information, see the this page for elements that can be used in the xml file and this other page for a sample config.xml

 

Important Note: There is an id attribute in the config.xml that MUST remain the same between builds. This bit me recently as I copy/pasted a sample config.xml and altered it to fit my needs. The ID was 'HelloWorld' and now that I've submitted it to appworld I cannot change it to another ID. This is a relatively small thing since users don't see the id, but it makes keeping track of things more difficult during dev.

Build and Deploy the WebWorks Application

With your Config.xml file completed we can build the webworks application and deploy it. RIM provides Command line tools to do the building, signing and deploying

 

Build with Debug Token

When you build with the -d switch you can attach a remote debugger to the phone to debug JavaScript (Looks and feels like the Chrome debugger tools). To build this way, use a command like this:

C:\Program Files (x86)\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.4.5>bbwp C:\Dev\PocketBombsClassic -d -o C:\temp

Note: Generalized form is bbwp <Path to folder with index.html> -d -o <output path>

Note 2: You need to cd to the WebWorks folder in Program Files for this command to work

Note 3: The output folder will have 2 folders named simulator and device. When deploying to your device, be sure to pick the correct .bar file

Output:

DebugTokenBuild.png

 

Build and Sign

Signing your application with the -g switch allows your app to be deployed to appworld as well as to your device. You will need your keystore password for this to work. Here's what it looks like:

C:\Program Files (x86)\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.4.5>bbwp C:\Dev\PocketBombsClassic -g passwordHere! -o C:\temp
 

Note: Generalized form is bbwp <Path to folder with index.html> -g <Signing Keystore Password > -o <output path>
 

Note 2: You need to cd to the WebWorks folder in Program Files for this command to work

Note 3: The output folder will have 2 folders named simulator and device. When deploying to your device, be sure to pick the correct .bar file

Output:

SignedBuild.png

 

Deploy to device / simulator

Once you have your webworks application built, you can deploy it to your test device using this command:

c:\Program Files (x86)\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.4.5\dependencies\tools\bin>blackberry-deploy -installApp -password 1234 -device 169.254.0.1 -package C:\temp\device\PocketBombs.bar

Note: The generalized form looks like this: blackberry-deploy -installApp -password <devicePassword> -device <IP Address of device or simulator> -package <path to the compiled .bar file>

Note 2: You need to be in the WebWorks SDK\dependencies\tools\bin folder for this command to work

Output:

DeployWebworksApp.png

Final Word

The WebWorks SDK documentation has improved immensely since I first looked at it a year ago. All my article here does is show an overall 'flow' from information that can be freely found on RIMs developer.blackberry.com website.

If you work with Cocos2d-x HTML5 you should have no difficulty getting your game to run in WebWorks. I was able to take the JavaScript version of my PocketBombs game and compile it for Webworks easily. The only issues I had related to my placement of shared javascript libraries- no problem could be traced back to webworks.