Deploying a BlackBerry WebWorks app to the PlayBook from Windows

Back in 2007 I wrote a BlackBerry OS application to perform a simple e-mail routing health check procedure. It turned out to be a hellish process, and not just for the fact that I’m not much of a Java developer (I don’t include Java in my list of skills on my resume). That was a minor problem compared to the overly involved process that had to be undertaken in order to simply compile the damn app and deploy it to a handheld for testing. On top of all that, Research In Motion at that time required that any developer who wished to use certain parts of their API, even just to test on their own device, to register at the cost of $200 USD. My employer paid this fee on my behalf, but it capped off an unpleasant process.

Times have changed and RIM has learned a few lessons. Developers no longer have to pay RIM merely for the pleasure of developing an app, but they do still face an unclear process for deploying to a test device. For both my own sake and for other developers, I’ve attempted to do a comprehensive write up of the process of deploying a BlackBerry WebWorks app to a PlayBook tablet. It consists of ten rather involved steps, but after the first time you do it once the process shrinks down to just the two last steps.

All right – let’s both take a deep breath and get started.

Before you attempt to deploy a WebWorks app, fill out the BlackBerry Code Signing Keys Order Form. While this costs you nothing, there is a 24 to 48 hour delay to recieving your key, so try to do this as soon as possible. You will eventually receive two *.CSJ files by e-mail that will allow you to complete the rest of this process: A ‘PDBT’ token used during your debugging, and an ‘RDK’ token used to sign your completed app when you submit it to the App World. Make note of your Registration PIN as you’ll need this in a step listed below.

Step One

Download Adobe AIR SDK 2.7 and the BlackBerry WebWorks SDK for Tablet OS for Windows. (For the WebWorks SDK download, you’ll need to register before you can download the EXE installation file.)

Step Two

Unzip the Adobe AIR SDK to C:\Program Files (x86)\AdobeAIRSDK . Install the WebWorks SDK to the default location (on my Windows 7 PC, that was to C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6 ).

Step Three

Now that we’ve got all of the utilities of the SDK set up, we’ll set up our Windows PC and get rid of the Windows error message to be able to sign applications to be deployed to a tablet in development mode. Open a Command Prompt and input the following:

cd ".\bbwp\blackberry-tablet-sdk\bin"
blackberry-keytool -genkeypair -keystore sigtool.p12 -storepass myp12password -dname "cn=My Company Name" -alias author
blackberry-signer -csksetup -cskpass mycskpassword
blackberry-debugtokenrequest -register -cskpass mycskpassword -csjpin myregistrationpin mycsjfile.csj

To explain each of these lines step by step:

  • Line #1 changes the directory to the \bin folder of the BlackBerry Tablet SDK.
  • Line #2 creates the file sigtool.p12 using the password value of myp12password and the author My Company Name. I’m told that commas in the author name cause issues, so avoid that.
  • Line #3 sets up long term keys for communication with the signing authority server under the password mycskpassword, and generates the file mycsjfile.csj.
  • Line #4 registers your machine with the signing authority server, referencing your CSK password of mycskpassword, the Registration PIN you entered in the BlackBerry Code Signing Keys Order Form (myregistrationpin) and the ‘PDBT’ *.CSJ file you received via e-mail.

Step Four

To move forward, we need an app to deploy. For the purposes of this guide, let’s deploy a sample application we know works. Download Marco van Hylckama Vlieg’s Unit Converter application from GitHub (click the Downloads button on the right side, select the *.ZIP file). Unzip that application into a local directory (for our example, C:\Development\UnitConverter\ ).

Step Five

Create a zipfile out of the contents of C:\Development\UnitConverter\ (the root directory should have config.xml in it, not a directory containing that file and others) and place it at C:\Development\UnitConverter.zip. Then run the following command which will create the file C:\Development\UnitConverter.bar:

".\bbwp\bbwp.exe" "C:\Development\UnitConverter.zip" -o "C:\Development"

Step Six

Let’s prep our physical PlayBook tablet to accept apps in development mode. Swipe down from the menu screen to reveal the configuration menu. Select Security, Development Mode, and set Use Development Mode to On. You’ll be required to set a password, which for this example will be devicepassword.

When this is complete, swipe the configuration menu back upwards and take notice of the new icon of a person with a gear in the top-right corner of the PlayBook’s display. Tap this icon to reveal the Development Mode menu. Take note of the IP Address value, as we’ll need it for the next step (for this example, we’ll use the value of 192.168.1.101).

Step Seven

Our next step is to create a debug token that allows us to place test versions of applications on our PlayBook tablet. Open a Command Prompt and input the following:

cd ".\bbwp\blackberry-tablet-sdk\bin"
blackberry-debugtokenrequest -cskpass mycskpassword -keystore sigtool.p12 -storepass myp12password -deviceId 0x12345678 "C:\Development\DebugToken.bar"
blackberry-deploy -installDebugToken "C:\Development\DebugToken.bar" -device 192.168.1.101 -password devicepassword

To explain each of these lines step by step:

  • Line #1 changes the directory to the \bin folder of the BlackBerry Tablet SDK.
  • Line #2 creates a debug token as a *.BAR file, requiring your mycskpassword, your keystore file sigtool.p12, the password to your keystore myp12password, your PlayBook’s PIN (About > Hardware > PIN) with the characters 0x placed in front (0x12345678), and the path and filename of the new debug token file, C:\Development\DebugToken.bar.
  • Line #3 transmits the debug token to your PlayBook, requiring you to input the tablet’s IP address 192.168.1.101 and the password you set in development mode, devicepassword.

Step Eight

We need to add a blackberry-tablet.xml file to your application, and will need to retrieve two values from our packager first. Run the following:

blackberry-airpackager -listManifest "C:\Development\DebugToken.bar"

Scroll back up through the output and make note of the following values:

Package-Author: My Company Name
Package-Author-Id: gYg7vhn3Q-5hjwnvbn67ckm3uvn

Create a new file called blackberry-tablet.xml in the same folder of your app as config.xml with the following contents:

<qnx>
	<author>My Company Name</author>
	<authorId>gYg7vhn3Q-5hjwnvbn67ckm3uvn</authorId>
	<category>core.all</category>
	<action>play_audio</action>
	<buildId>1</buildId>
	<platformVersion>0.1.0.0</platformVersion>
	<icon>
		<image>icon.png</image>
	</icon>
</qnx>

Step Nine

Re-do Step Five (create a zipfile, output a *.BAR file) to repackage your app with the blackberry-tablet.xml inside it.

Step Ten

Would you believe this is the last step? It’s straightforward, too – it simply deploys your *.BAR file to your PlayBook:

".\bbwp\blackberry-tablet-sdk\bin\blackberry-deploy.bat" -installApp -password pass -device 192.168.1.138 -package "C:\Development\UnitConverter.bar"

You’re Done!

Assuming the result of your last step contained the message “result::success”, you’re done! Take a look at your PlayBook’s menus and select your application. It should start without issue and allow you to explore your app’s performance on a real-world PlayBook device.

As mentioned earlier, after this first deployment you’ll only ever have to re-run Step Nine and Step Ten to load updated copies of your app onto the device (plus the occasional upload of a new debug token, as each last 10 days).

References

4 Comments

  1. Edy Braun

    Thanks for the info! Really helped a lot, especially regarding all these debug tokens and such! Saved me hours of figuring things out. I had problems loading it onto the playbook originally, kept giving me the “500 error author not the same” issue, until you mentioned you ALSO have to have a “blackberry-tablet.xml” file with the author and authorid also included.

    However, I still encountered a few problems along the way. Here they are, in case it helps others:

    First, the “blackberry-tablet.xml” file wouldn’t recognize my icon. When compiling using bbwp it would complain that it couldn’t find it “Error: Attribute Entry-Point-Icon: file cannot be found in the list of packaged file: icon.png”. I had the icon file “icon.png” in my root folder of the ZIP file, same folder as the “blackberry-tablet.xml” file and the “config.xml” file which had the img src= tag pointing to it. So I couldn’t figure out why it couldn’t find the icon file.

    Second, in “blackberry-tablet.xml” file, wouldn’t recognize the tag at all, had to erase it also. I received this error also with bbwp when trying to compile: “Warning: unknown category: core.all”. So I got rid of that too.

    So after deleting those lines from the blackberry-tablet.xml file, I was finally able to compile the BAR successfully, and load it onto my Playbook. The icon worked fine (guess it used what was in the config.xml file as it ignored the blackberry-tablet.xml). So happy to have my first debug version working!!!

    Now time to develop and finish my app… I can’t wait to see what happens when I have to submit to AppwWorld, what kind of grief I am going to encounter. :-)

  2. An Pham

    I have successfully created a debug token.
    After that, I installed it on playbook successfully.

    I have just deploy my webworks app on my playbook follow this guide!
    I try to implement step to step,

    The cmd line of the “Step Ten”:
    C:\Program Files\Research In Motion\blackberry-tablet-sdk-1.1.1\bin>blackberry-deploy -installApp -password playbook -device 169.254.0.1 -package D:\C\device\Converter.bar
    Info: Sending request: Install
    Info: Action: Install
    Info: File size: 2269
    Info: Installing …
    Info: Processing 2269 bytes
    actual_dname::debug.token.gYABgHN2sVepeOFu_NXRX7cfZTU
    actual_id::gYABgHN2sVepeOFu_NXRX7cfZTU
    actual_version::0.0.0.3
    result::success

    But my webworks app is not apeared on my playbook!
    Could you show me the reason?

    I am expecting your respone soon!

    Best Regards,
    An Pham

  3. Shyla

    First of all, Thank you Syed for this post. This helped me immensely as I was getting bogged down with the process.

    for those who have trouble viewing the app from blackberry after a successful install, I used -launchApp option. So the app installed and then launched when it was done.

    command would be something like

    blackberry-deploy -installApp -launchApp -password playbook -device 169.254.0.1 -package D:\C\device\Converter.bar

    Hope this helps.

Leave a Reply

Your email address will not be published. Required fields are marked *