Convert any SWF into a BlackBerry 10.2 Application (GAP for AIR)

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

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

Normally, to convert SWFs into for BlackBerry 10 apps, you have to use the command line, which is not very comfortable and productive for some developers, myself included. You can also use IDEs, but sometimes you want to just use a simple GUI tool.

With that in mind, the Tech Center Maceio in Brazil and I designed/developed a visual tool for the desktop (Mac and Windows) called GAP (Graphical Aid Plus) Alpha for AIR, which executes all the command line instructions under the hood.

As you might know, BlackBerry 10.2 now supports Adobe AIR 3.5, which includes Stage3D and StageVideo, great APIs for games and video. With GAP Alpha for AIR you can convert any SWF into a BlackBerry 10.2 application.

Let me tell you how it works!

1. Download and Install GAP

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

Download GAP Alpha for AIR (Mac Version, 29.9MB)
Download GAP Alpha for AIR (Windows Version, 22.9MB)

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
  • Create BB10 apps from any SWF
  • Install .bar files in the simulator or any device

2. Set 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 BlackBerry 10 SDK for Adobe AIR is installed.

Default location of the BlackBerry 10 SDK for Adobe AIR:
Windows (x64): \Program Files\Research In Motion\blackberry-tablet-sdk-a.b.c
Windows (x86): \Program Files (x86)\Research In Motion\blackberry-tablet-sdk-a.b.c
Mac: /Applications/Research In Motion/blackberry-tablet-sdk-a.b.c

3. Request Signing Keys

To request signing keys normally you go to https://www.blackberry.com/SignedKeys/, check the platform (in our case “For BlackBerry 10 apps developed using BlackBerry NDK, AIR, or Android, or for BlackBerry PlayBook apps developed using Android. Requires BlackBerry 10.2 Gold or higher SDK.”), 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, choosing your PIN, reading and accepting the agreement, and hitting submit – all right from the app.

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.

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”.

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.

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.

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.

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”.

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

7. Create 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 user’s computer, 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).

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)

8. Install 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.

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. Create BB10 apps from any SWF

To build (package) your BlackBerry 10 AIR 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 where your SWF is located.

If you leave SIGN checked, the .bar will be created and then the app will be signed. If you uncheck SIGN, you will have to use debug tokens to test the .bar file on BB10 devices.

If you are targeting AIR 3.2 or higher, make sure you uncheck VALIDATE SDK. If you leave VALIDATE SDK checked, you have to update your AIR descriptor file (ex: test-app.xml) second line to AIR 3.1 or lower:
application xmlns=”http://ns.adobe.com/air/application/3.1” (VALIDATE SDK checked)
application xmlns=”http://ns.adobe.com/air/application/3.5” (VALIDATE SDK unchecked)

With your SWF, you have to have:

  • One 114px x 114px PNG file for your icon
  • An AIR descriptor file (ex: test-app.xml)
  • A bar-descriptor.xml file

If you don’t have a bar-descriptor.xml file, GAP can create one for you when you select the folder to build the app:

The bar-descriptor.xml file describes your application, you might need to uncomment/change the tags author and authorId if you are not signing your app (using debug tokens).

The descriptor file (ex: test-app.xml) describes all the information regarding AIR:

If you are using Stage3D, make sure you set the tag renderMode to direct:

Once everything is set, click on “Build”. Wait for the completion message and you will have your .bar file created.

10. Install 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”.

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

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

Happy coding everyone!

Wow. It's Quiet Here...

Be the first to start the conversation!

Leave a Reply:

Gravatar Image