Creating HTML5 Apps for BlackBerry 10 Without Touching the Command Line

Community

Important: This is not an official BlackBerry tool and there is no plan to provide support/updates. Use it at your own risk.

TITLE_IMAGE

Hello fellow web developers! This is Demian Borba, BlackBerry Developer Evangelist and I’d like to share something special with you all.

Building HTML5 apps for BlackBerry 10 requires you to use the command line, which is not very comfortable and productive for some developers, myself included. There are some plugins and extensions for tools like Sublime Text 2, but sometimes you want to just use a great GUI tool.

With that in mind, the Tech Center Maceio in Brazil designed and developed a visual tool for the desktop (Mac and Windows) called GAP (Graphical Aid Plus) Alpha for HTML5, which executes all the command line instructions under the hood. The scope was defined around all the feedback we collected from developers who were part of our super hackathons last year.

Let me tell it how it works!

1. Download and Install GAP

Before you download GAP Alpha for HTML5, please make sure you download and install the current BlackBerry 10 WebWorks SDK.

Click here to download the GAP Alpha for HTML5 for the Mac (29 MB)
Click here to download the GAP Alpha for HTML5 for Windows (22 MB, open the .exe to start)

Once you have GAP installed, you will be able to (visually):

  • Request signing keys
  • Register signing keys
  • Backup signing keys
  • Restore signing keys
  • Create and install debug tokens
  • Build WebWorks apps
  • Install .bar files in the simulator or any device

Graphical Aid Plus Alpha for HTML5

 

2. Setting Up Gap

After you install and open GAP, the first screen that opens is the Settings screen, where you:

  • Save your keystore (to be used to sign applications)
  • Point to the root folder where your WebWorks SDK is installed

On a PC the path typically is C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK a.b.c.d
On a Mac the path typically is \Macintosh HD\Developer\SDKs\Research In Motion\BlackBerry 10 WebWorks SDK a.b.c.d.

Settings Screen

 

3. Requesting Signing Keys

To request signing keys normally you go to https://www.blackberry.com/SignedKeys/, check the platform (in our case “For BlackBerry PlayBook OS and BlackBerry 10 and Higher”), fill out the form, choose your PIN, read the agreement, accept it and hit submit.

With GAP, once you click on “Request Signing Keys”, you get to the same form, but the BlackBerry 10 option is already checked for you and you can concentrate on filling out the form, choosing your PIN, reading and accepting the agreement, and hitting submit - all right from the app.

Request Keys

If you need to request more keys for different developers, just click on “Refresh” and repeat the process above as many times as necessary.

You will receive two .csj files in two separate emails (please save them on your hard drive):

client-RDK-xxxxxx.csj:
This is the file that you use to sign your applications and publish to BlackBerry World;

client-PBDT-xxxxx.csj:
This file is used to generate a debug token that you can use to test your application on a device.
These files can only be used/registered once.

Downloaded Files

 

4. Register Signing Keys

After saving the two .csj files on your computer, you will need to register them. On GAP, please click on “Certificate” and then on “Register your keys and create certificate”.

Registering Options

Select the two .csj files from you computer, type the same PIN you used when you requested your keys and then click on “Register”. Your computer will then communicate with BlackBerry servers to register your keys. Wait for the success message and your computer is registered.
Important: if you are using VPN, please make sure to disconnect before attempting to register.

Select Files and Click On Register

 

5. IMPORTANT!! Backup Your Signing Keys

As soon as your keys are registered, please do a backup. Why?
Because if you sign an application using your keys and submit it to BlackBerry World, when you make an update to your application, you will need to use the same keys to sign the updated app. If you sign your updated application with different signing keys (from a different computer for instance), when you upload it to BlackBerry World, it will be interpreted as a new/different application. It will be a mess! There are ways to revert this, but you will have to contact BlackBerry World, reset your app, your old app will have to be deleted etc. In order to avoid this please play safe –  backup your keys.

In the future, if you change computers, you will be able to restore the same keys from your backup.

Backup Your Keys

Once you click on “Backup”, three files will be saved on your computer:

  • author.p12 (your certificate)
  • barsigner.csk
  • barsigner.db

Please save them on a safe location, you probably will need to restore them in the future.

Backup Files

 

6. Restore Your Keys and Certificate

As soon as you change computers and need to update an application on BlackBerry World, you will need to have the new computer registered with the same keys and certificate used to sign the application once submitted to BlackBerry World.

In order to do that, please click on “Certificate”, then on “Restore your keys and certificate”. Select the root folder that contains the 3 files (your backup) and click on “Restore”.

Select The Folder With Your Backup

After getting the confirmation of “successfully registered with servers”, you are good to go.

 

7. Creating Debug Tokens

In order to install .bar files (BlackBerry 10 apps) on BlackBerry 10 devices or submit them to BlackBerry World, the application has to be signed (we will see how to sign them in a second). But some developers don’t like to sign every single time the .bar is created.

You can install non-signed apps on BlackBerry 10 devices, but you will have to have a debug token installed on your device. The debug token is a file (named debugtoken.bar) which has to be saved in the root of the WebWorks SDK before uploaded to the device, but don’t worry, when you create one using GAP, it saves the debug token with the right name in the right location.

The debug token lasts 30 days and, during this period, you can install non-signed apps on BlackBerry 10 devices (if the device PINs are included in the debug token).

Debug Token

To create a debug token, please click on “Debug Token”, then click on “New”, then insert the PIN (or PINs) of the device (or multiple devices) which will receive the non-signed app (.bar file). To register more than one device, insert the PINs separated by comma.
To get a device PIN, on the home screen, swipe down from the top bezel to go to “Settings > About > Category Hardware” (e.g. 25D80E29)

Create Debug Token For Your Device(s)

 

8. Installing Debug Tokens

Once you have the debug token created (remember that GAP saves it on the right location with the right name), you will need to upload (install) it to your device (or devices). To do that, click on “Debug Token”, then on “Install”. Type your device IP address (if it’s connected to your computer via USB, the IP is 169.254.0.1), but you can also upload it via network (using the right network IP address).
Before you click on install, please grab your device and turn “Development Mode” on. To do that, on your device, go to “Settings > Security and Privacy > Development Mode” and turn on the top switch.
Now you are ready to upload your debug token. Using GAP, click on “Install” and wait for the success message.

Install Debug Token

Sometimes the debug token is uploaded but the “Development Mode” screen, on the device, doesn’t update showing it’s installed. So go back one level to “Security and Privacy” and re-enter on the “Development Mode” screen. Once it’s installed, you will be able to view the debug token information (such as Author and Expiration Date).

 

9. Building Your HTML5 App

To build (package) your BlackBerry 10 WebWorks App as a .bar file using GAP, please go to “Build App” and, on the “Project Folder” field, select the root folder of your project (containing your HTML files, CSS files, JS files and all the necessary local assets such as images and sounds). There is no need to ZIP your files.

Build App

Also set the Bar File location (where your .bar will be saved) + file name on the “Bar File Location” field.

You can generate three kinds of .bar files:

  • RELEASE (SIGNED): to submit to BlackBerry World or install on any device (don’t need a debug token)
  • BETA (SIGNED WITH DEBUG MODE ON): to install and test on any device (don’t need a debug token)
    You can debug it by entering on Chrome on your computer the device IP + the special port 1337. (e.g. type on chrome’s address field: 169.254.0.1:1337), you will then access the Remote Web Inspector. 
  • DEBUG (NON-SIGNED): non-signed .bar file to be tested on devices with debug token installed.
    You can debug it by entering on Chrome on your computer the device IP + the special port 1337. (e.g. type on chrome’s address field: 169.254.0.1:1337), you will then access the Remote Web Inspector.

You will have to have a config.xml also present in your root folder. If you don’t have one, GAP notices it and asks to create one for you. If you click on “Create”, it will place a config.xml template file in your project root folder.

Config.xml creator

If the config.xml was generated by GAP, please open it with your favorite text editor and update the right tags with your project information. The tags that have to be updated are:

  • type your href author/company website and your author/company name
  • type the name of your application. Will show up below the launch icon on the home screen
  • type the description of your application
  • uncomment all the necessary permissions, such as camera, bbm_connect etc
  • type the image icon local path (it has to be a PNG with 114px x 114px)
  • list all the possible splash screens (WebWorks will figure out the right one to display)
  • type the first page that opens (e.g. index.html)

<param name=”websecurity” value=”disable” /> allows you to load and execute JS files from external servers. If you disable websecurity, you won’t need to whitelist the servers that will be called.

Config.xml Template

Once everything is set, click on “Build”. Wait for the completion message and you will have 2 bar files created, one for devices and for the simulator.

 

10. Installing Your App On Your Device or Simulator

After you have a .bar file ready to be installed, go to the “Install App” screen, set the device IP (or simulator IP), set the device password, locate the .bar file to be installed and click on “Install”.

Install App

Just wait for the success message and the app will be installed on your device or simulator.

Happy coding everyone!

Please send your feedback about GAP Alpha for HTML5 to ufal@blackberrydeveloper.com.br

Credits to Iago Barboza (Developer), Dieges Lima (Designer) and Leandro Sales (ScrumMaster and Coordinator), members of the Tech Center in Brazil at Federal University of Alagoas, supervised by me (@demianborba) and Rodrigo Peixoto (Application Development Consultant), not forgetting the extra help from Tainá Ribeiro (Designer) and Dielson Sales (Developer).

I have prepared a 9 minute video to summarize all the steps of using GAP Alpha for HTML5:

Click here to download the GAP Alpha for HTML5 for the Mac (29 MB)
Click here to download the GAP Alpha for HTML5 for Windows (22 MB, open the .exe to start)

About demianborba

With more than 13 years of experience with technology, interactive media, design, business and training, I have worked as one of the Adobe Community Professionals and also as a professor at UC San Diego, teaching UI Design and Programming classes for Design and Computer Science students. Before joining BlackBerry, I ran Action Creations, an interactive agency based in San Diego with clients including Oakley, 20th Century Fox, World Tour of Surfing, Nike, Callaway Golf and more. In the community arena, I was the organizer of one of the largest Adobe community events in the world, called Adobe Camp Brasil. In 2012, I had the chance to participate and win one of the biggest and most important developer contests in the world, the AT&T® Mobile App Hackathon, at CES in Las Vegas USA. Recently, I had the honor to receive the "Must See BlackBerry Developer Evangelist" Award at Jam Americas in San Francisco.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus