Requirements
Prerequisite knowledge
Familiarity with building RIAs using Flash Builder.
Article: Configuring Flash Builder 4.5 to build apps for BlackBerry Tablet OS
Required products
Flash Builder (Download trial)
User level
All

Note: This is an updated and expanded version of an article originally written by Andrew Shorten.
 
Flash Builder 4.5 includes support for packaging Flex and ActionScript applications for Google Android, Apple iOS, and BlackBerry Tablet OS devices. The process for acquiring signing certificates and provisioning application packages for the various platforms differs significantly.
 
This article and video aim to help ActionScript and Flex developers complete the necessary steps so that applications built in Flash Builder can be deployed to BlackBerry Tablet OS devices during the development, testing and deployment phases of the project.
 
For more information on packaging applications for other platforms please read the following articles:
 

 
Run and debug in a simulator

To test your application during development, you can run and debug it on a connected device or in a simulator. A simulator provides a quick and easy way to run the application without needing to undertake the signing/provisioning process, but of course has limitations in that it can't exaclty replicate performance of an actual device. You can simluate the application using the Flash Builder device emulator or the more sophisticated BlackBerry PlayBook Simulator.
 
Step 1: Run the application in the Flash Builder device emulator.
 
The Flash Builder device emulator is the fastest way to see what your application will look like on a BlackBerry Tablet OS device. It shows the application in a window with the correct size and resolution. It also has a device menu to simulate device rotation and several device buttons.
 
  1. In Flash Builder, select Run Configurations from the Run menu or from the dropdown list for the Run button and click the new or duplicate button to create a new run configuration.
  2. Name the new configuration, set the target platform to BlackBerry Tablet OS, set the launch method to On desktop, and select BlackBerry PlayBook (see Figure 1).
Figure 1. Create a run configuration for a BlackBerry PlayBook using the device emulator.
Figure 1. Create a run configuration for a BlackBerry PlayBook using the device emulator.
 
Note: If you do not have the Blackberry Tablet OS target platform option, go to Project > Properties > Flex or ActionScript Build Packaging > BlackBerry Tablet OS and select Enable this target platform.
 
  1. Click the Run button. Flash Builder launches the application in the Flash Builder device emulator (see Figure 2).
Figure 2. Run the application with the Flash Builder emulator.
Figure 2. Run the application with the Flash Builder emulator.
 
Step 2: Download and install the BlackBerry Tablet OS SDK.
 
To run in a simulator that more closely mimics the BlackBerry Playbook experience, download, install, and set up the BlackBerry PlayBook Simulator.
 
The first thing you need to do is download and install the BlackBerry Tablet OS SDK. It contains the code for integrating with Flash Builder to run and debug on a BlackBerry Tablet Simulator as well as the code to run and debug on a device and to create a release build of an application for the BlackBerry App World store.
 
  1. Go to the BlackBerry main web page for developing AIR applications for the BlackBerry Tablet OS.
  2. Locate the link to download the BlackBerry Tablet OS SDK for AIR for your operating system (Windows, Mac, Linux) (see Figure 3).
Figure 3. Download the SDK.
Figure 3. Download the SDK.
 
  1. If you are a registered BlackBerry Developer Zone Member, log in; otherwise, click the plus sign next to Not a BlackBerry Developer Zone Member, enter your personal information, and click next. In the latter case, there is an optional check box to use this information to become a Blackberry Developer Zone Member.
  2. Download the SDK.
  3. Close Flash Builder if it is open.
  4. Run the installer to install the SDK. Note the location where you install the SDK; you may want to install it in the Flash Builder sdks folder although this is not the default location. The BlackBerry PlayBook Simulator is installed with the BlackBerry Tablet OS SDK (see Figure 4).
Figure 4. Download and install the BlackBerry Tablet OS SDK.
Figure 4. Download and install the BlackBerry Tablet OS SDK.
 
Step 3: Register the BlackBerry Tablet OS SDK path in Flash Builder.
 
In order to run an application in the BlackBerry PlayBook Simulator or on a device, you need to register the SDK in Flash Builder.
 
  1. In Flash Builder, go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS.
  2. Click Browse and navigate to where you saved the BlackBerry Tablet OS SDK.
  3. Click OK (see Figure 5).
Figure 5. Register the SDK in Flash Builder.
Figure 5. Register the SDK in Flash Builder.
 
Step 4: Download and install VMWare.
 
The BlackBerry Playbook Simulator requires VMWare. If you want to debug your application with the simulator before testing on an actual device, you need to download and install VMWare if you do not already have it. You can get a 30-day, fully featured free trial before you buy.
 
  1. Go to the BlackBerry main web page for developing AIR applications for the BlackBerry Tablet OS.
  2. Locate the link to download VMWare for your operating system (Windows, Mac, Linux) (see Figure 6).
Figure 6. Download VMWare.
Figure 6. Download VMWare.
 
  1. Download and install VMWare.
  2. Open VMWare and click the Get Serial Number button and enter your serial number or follow the links and process to get a 30-day serial number.
Step 5: Install and start the BlackBerry PlayBook Simulator.
 
Next, install and start the BlackBerry PlayBook Simulator.
 
  1. In VMWare, select File > Open and browse to the BlackBerryPlayBookSimulator folder located in the BlackBerry-tablet-sdk folder.
  2. Select the BlackBerryPlayBookSimulator.vmx file and click Open.
  3. Click OK. The BlackBerry Playbook Simulator will load (see Figure 7).
Figure 7. Start the BlackBerry PlayBook Simulator.
Figure 7. Start the BlackBerry PlayBook Simulator.
 
Step 6: Get the IP addess of the BlackBerry PlayBook Simulator.
 
In order to run your application in the simulator, you need to provide Flash Builder its IP address. Each time the BlackBerry PlayBook Simulator starts, VMware Fusion assigns it an IP address. To display the IP address, the simulator must be in development mode, which is enabled by default in the simulator.
 
In the BlackBerry PlayBook Simulator, click the icon to the right of the clock on the status bar (see Figure 8) and get its IP address.
 
Figure 8. Get the IP address of the BlackBerry PlayBook Simulator.
Figure 8. Get the IP address of the BlackBerry PlayBook Simulator.
 
Step 7: Register the simulator as a test device in Flash Builder.
 
Now that you have the simulator's IP address, you can register it as a test device in Flash Builder.
 
  1. In Flash Builder, go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Test Devices.
  2. Click Add and then specify the following information (see Figure 9):
    • Device Name: PlayBook Simulator
    • Device IP: <IP address – as obtained from the simulator>
    • Password: playbook
Figure 9. Add the BlackBerry Playbook Simulator as a test device.
Figure 9. Add the BlackBerry Playbook Simulator as a test device.
 
  1. Click OK. The PlayBook Simulator will now be listed as a test device (see Figure 10).
  2. Click OK to close the Preferences dialog box.
Figure 10. Register the BlackBerry PlayBook Simulator as a test device.
Figure 10. Register the BlackBerry PlayBook Simulator as a test device.
 
Step 8: Run an application in the BlackBerry PlayBook Simulator.
 
You are now ready to run an application in the simulator.
 
  1. In Flash Builder, select Run Configurations from the Run menu or from the dropdown list for the Run button and click the new or duplicate button to create a new run configuration.
  2. Name the new configuration, set the target platform to BlackBerry Tablet OS, set the launch method to On device, and select PlayBook Simulator (see Figure 11).
Figure 11. Create a run configuration for running in the BlackBerry PlayBook Simulator.
Figure 11. Create a run configuration for running in the BlackBerry PlayBook Simulator.
 
  1. Click the Run button. Flash Builder will create an application package, connect to the simulator, and deploy the application (see Figure 12).
Figure 12. Run the application in the BlackBerry PlayBook Simulator.
Figure 12. Run the application in the BlackBerry PlayBook Simulator.
 
  1. Swipe up from the bottom of the simulator window (just as you would on an actual PlayBook) to return to the main view. You will see an icon for your application (see Figure 13). You will learn to customize the application name and icon in a later section.
Figure 13. Locate the debug version of the application installed on the simulated PlayBook.
Figure 13. Locate the debug version of the application installed on the simulated PlayBook.
 
  1. Return to Flash Builder and locate the BAR application package file in your project's bin-debug folder (see Figure 14). This is a debug version of the application for development. You learn to create a release version of the BAR for distribution in a later section.
Figure 14. Locate the debug BlackBerry Tablet OS package created.
Figure 14. Locate the debug BlackBerry Tablet OS package created.
 

 
Get the required certificates

Before you can run and debug an application on a device, you must use Flash Builder to create a developer certificate and create and upload a debug token onto the device. To create a certifcate with Flash Builder, you need to first obtain code signing keys from RIM. This process is free of charge, but can take up to 48 hours to complete.
 
Step 1: Obtain BlackBerry code signing keys.
 
Browse to the BlackBerry Code Signing Keys Order Form and fill out and submit the form (see Figure 15). Be sure to set the key field to BlackBerry Tablet OS Code Signing Key. After you submit the form, you will receive an order confirmation email from RIM.
 
Make sure you remember the company name you specify here and the PIN you set. You will need both of these values later.
 
Figure 15. Register for code signing keys.
Figure 15. Register for code signing keys.
 
Step 2: Get the code signing CSJ files.
 
Within 48 hours, you should receive two emails from RIM, each with a CSJ registration file attached (see Figure 16). Save the client-RDK.csj and client-PBTD.csj files to your computer.
 
Figure 16. Get and save the CSJ files.
Figure 16. Get and save the CSJ files.
 
Step 3: Register with the RIM Signing Authority in Flash Builder.
 
Once you receive the CSJ files, you can register with the RIM Signing Authority in Flash Builder.
 
In Flash Builder, go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Signing.
 
  1. Click the Register button, browse to the two CSJ files, and then complete the remainder of the information (see Figure 17). For the CSJ PIN, use the PIN you set when registering for the code signing keys. You create a CSK password here.
  2. Note: You need to be online when completing this registration because Flash Builder must communicate with RIM to complete the registration process. If you need to configure Flash Builder to communicate via a proxy server, refer to the documentation on the RIM website.
     
Figure 17. Register with the RIM Signing Authority.
Figure 17. Register with the RIM Signing Authority.
 
  1. Click OK. On the Signing page, you should see that you are now registered (see Figure 18). You can only register with the RIM Signing Authority once for a set of CSJ files.
Figure 18. Successfully register with the RIM Signing Authority.
Figure 18. Successfully register with the RIM Signing Authority.
 
 
Step 4: Generate a P12 developer certificate.
Next, you use Flash Builder to create a developer certificate. You need this certificate to create a debug token and to sign applications for packaging.
 
  1. Go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Signing and click the Create Certificate button.
  2. In the Create Developer Certificate dialog box, browse to where you want to save the certificate and assign it a file name.
  3. In the Create Developer Certificate dialog box, set the author to the company name you entered when requesting the code signing keys from RIM (see Figure 19). The author you specify here must match the company name (not the person name) you entered when registering for the code signing keys. If the two do not match, the certificate will still be created successfully, but the process will fail when you try to create a debug token or sign the application using the certificate in the next sections.
Figure 19. Create a developer certificate in Flash Builder.
Figure 19. Create a developer certificate in Flash Builder.
 
  1. Set and confirm a password and click OK. You should see the certificate listed in the top of the Signing page (see Figure 20).
Figure 20. Set the developer certificate.
Figure 20. Set the developer certificate.
 

 
Run and debug on a device

To run and debug an application on a BlackBerry Tablet OS device, you need to create and install a debug token on the device. You use Flash Builder to create a debug token and then configure your application with the author and author ID specified in the debug token so that the application can run without being signed.
 
Step 1: Make sure the device has Adobe AIR 2.6 or later.
 
An application created with the Flex 4.5.1 SDK requires Adobe AIR 2.6 or later to run.
 
  1. In Flash Builder, open the application's application descriptor file and check the required AIR version (see Figure 21).
Figure 21. Look up the AIR runtime version required by the application.
Figure 21. Look up the AIR runtime version required by the application.
 
  1. On the device, go to Settings > About, select OS from the drop-down list, and locate the AIR version installed on the device (see Figure 22).
Figure 22. Locate the AIR version on the device.
Figure 22. Locate the AIR version on the device.
 
  1. If the device does not have the required AIR version, go to Settings > Software Updates and click Check for Updates; if there is a later version of software available, install it.
Step 2: Enable development mode on the device.
 
To run the application on the device, the device must be in development mode and you need its development password.
 
  1. On the device, go to Settings > Security > Development Mode.
  2. Set Use Development Mode to On. A Set Password dialog box will appear.
  3. In the Set Password dialog box, set and confirm a password. Development mode is now enabled and you will need to enter this password when using the device (see Figure 23).
Figure 23. Enable development mode on the device.
Figure 23. Enable development mode on the device.
 
Step 3: Get the device IP address.
 
To register the device with Flash Builder and create a debug token for it, you need its IP address.
 
On the device, click the Development icon to the right of the clock on the status bar (see Figure 24) and get its IP address.
 
Figure 24. Get the device IP address.
Figure 24. Get the device IP address.
 
Step 4: Register the device as a test device in Flash Builder.
 
You can now register the device in Flash Builder.
 
  1. In Flash Builder, go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Test Devices.
  2. Click Add, assign a device name and enter its IP address and its development password, and click OK (see Figure 25).
Figure 25. Register the device in Flash Builder.
Figure 25. Register the device in Flash Builder.
 
    Note: There is a check box to create a debug token from this dialog box, but I always get a error when trying to create the token this way; I will use a different process in the next steps.
     
  1. Click OK to close the Preferences dialog box.
 
Step 5: Connect the Blackberry Tablet OS device to the computer.
Connect the device to the computer with a USB cable.
 
 
Step 6: Create a debug token with Flash Builder.
A debug token must be installed on a device before Flash Builder can install a debug version of the application on it during development.
 
  1. In Flash Builder, return to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Signing.
  2. Click the Create button in the Debug Tokens section.
  3. In the Create Debug Token dialog box, click Add (see Figure 26).
  4. In the Add Devices dialog box, click Auto Discover (see Figure 26). For registered test devices, you can have Flash Builder retrieve the device's PIN number automatically. Alternatively, you can obtain a device PIN by selecting Settings > About > Hardware on the device.
  5. In the Auto Discover dialog box, select the device(s) (see Figure 26).
Figure 26. Auto discover device PINs.
Figure 26. Auto discover device PINs.
 
  1. In the Auto Discover dialog box, click OK. You will get an Upload Debug Token dialog box. Contrary to what it says in this dialog box, you do not need to place the device in debug token upload mode to get its PIN.
  2. In the Upload Debug Token dialog box, click OK. Flash Builder will connect to the device and retrieve its PIN number. Once the PIN is successfully retrieved, it is displayed in the Add Devices dialog box.
  3. In the Add Devices dialog box, Click OK.
  4. In the Create Debug Token dialog box, set the name and location for where the token will be stored and click OK (see Figure 27). You will get a Password dialog box.
Figure 27. Save the debug token file on your computer.
Figure 27. Save the debug token file on your computer.
 
  1. In the Password dialog box, enter the CSK password you set when registering with the RIM Signing Authority in Flash Builder.
  2. In the Password dialog box, click OK. The debug token file is created and saved (see Figure 28).
Figure 28. See the debug token in Flash Builder.
Figure 28. See the debug token in Flash Builder.
 
Step 7: Install the debug token on the device.
 
Once the debug token is created, you need to install it onto your BlackBerry Tablet OS device(s).
 
  1. On the device, go to Settings > Security > Development Mode and click Upload Debug Token. The device will wait for a debug token to be uploaded to it (see Figure 29).
Figure 29. Place the device in debug token upload mode.
Figure 29. Place the device in debug token upload mode.
 
  1. In Flash Builder, go to Flash Builder > Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Signing.
  2. Select the debug token and click Upload (see Figure 28).
  3. In the Upload Debug Token to Devices dialog box, select your device(s) (see Figure 30).
Figure 30. Select the device(s) to upload the debug token to.
Figure 30. Select the device(s) to upload the debug token to.
 
  1. Click OK. You will get an Upload Debug Token dialog box (see Figure 31).
Figure 31. Confirm your selection.
Figure 31. Confirm your selection.
 
  1. You already put the device in debug token upload mode, so click OK. The debug token will be uploaded onto the device. Once it is finished, you will see its info on the device (see Figure 32).
Figure 32. Locate the debug token info on the device.
Figure 32. Locate the debug token info on the device.
 
Step 8: Get your author ID value in Flash Builder.
 
Before you can run or debug an application on a device with a debug token installed, you must make sure the application's blackberry-tablet.xml file is configured with the correct author and author ID values.
 
  1. In Flash Builder, go to Preferences > Flash Builder > Target Platforms > BlackBerry Tablet OS > Signing.
  2. Select the debug token you are using and click the Details button. You will get a Debug Token Details dialog box (see Figure 33).
  3. Note the author name and copy the author id.
  4. Click OK to close the dialog box and then click OK to close the Preferences dialog box.
Figure 33. Get the debug token details in Flash Builder.
Figure 33. Get the debug token details in Flash Builder.
 
Step 9: Set the applications's author and author id in blackberry-tablet.xml.
 
Now you need to set the application's author and author id values to the values set in the debug token.
 
  1. Right-click blackberry-tablet.xml in the Package Explorer and select Open With > Text Editor.
  2. Replace the single <qnx/> tag with open and closing qnx tags: <qnx></qnx>.
  3. Add author and authorId elements and set them to the values you looked up in the debug token details in the previous step.
  4. Save the file.
<qnx> <author>MyCompany</author> <authorId>gYAAgIqK0RLL5u4I9NanyxBUuCI</authorId> </qnx>
Step 10: Set the application icon.
 
You also set the application icon to be used on the device in the blackberry-tablet.xml file. The icon should be 86-by-86 pixels (or smaller) PNG or JPG. An icon that is larger than 86-by-86 pixels will not display on the device screen.
 
  1. In blackberry-tablet.xml, add an icon element to the qnx tag.
  2. Inside the icon tag, add an image element equal to the path of the image file.
<qnx> <author>MyCompany</author> <authorId>gYAAgIqK0RLL5u4I9NanyxBUuCI</authorId> <icon> <image>assets/appicon86x86.png</image> </icon> </qnx>
Step 11: Set application permissions.
 
You also set application permissions in the blackberry-tablet.xml. You can look up possible values and type them in directly or you can select them a Flash Builder dialog box.
 
  1. Go to Project > Properties > Flex Builder Packaging > BlackBerry Tablet OS and click the Permissions button.
  2. Select all the permissions your application needs (see Figure 34).
Figure 34. Set application permissions.
Figure 34. Set application permissions.
 
  1. Click OK. If you selected any permissions, new permission elements will be added to your blackberry-tablet.xml file (see Figure 35).
Figure 35. Locate the added permissions.
Figure 35. Locate the added permissions.
 
Step 12: Set the application name and id.
 
Lastly, set the application name to appear on the device.
 
  1. Open the application-descriptor file.
  2. Set the name and filename elements to the value you want to use for the application and appear on the device (see Figure 36).
  3. Set the id element to a unique value; the application id must be unique across all AIR applications. The common convention is to use a reverse name notation for this value (see Figure 36).
Figure 36. Set the application name and id.
Figure 36. Set the application name and id.
 
Step 13: Run on a Blackberry Tablet OS device.
 
You are finally ready to run the application on a device.
 
  1. In Flash Builder, select Run Configurations from the Run menu or from the dropdown list for the Run button and click the new or duplicate button to create a new run configuration.
  2. Name the new configuration, set the target platform to BlackBerry Tablet OS, set the launch method to On device, and select one of your registered BlackBerry Tablet OS devices (see Figure 37).
Figure 37. Create a run configuration for running on a Blackberry Tablet OS device.
Figure 37. Create a run configuration for running on a Blackberry Tablet OS device.
 
  1. Click the Run button. Flash Builder will create the application package and install and launch the application on the device (see Figure 38).
Figure 38. Run the application on a BlackBerry Tablet OS device.
Figure 38. Run the application on a BlackBerry Tablet OS device.
 
  1. Swipe up from the bottom of the device to return to the main view and locate the icon for your application (see Figure 39).
Figure 39. Locate the icon for the debug version of the application on the device.
Figure 39. Locate the icon for the debug version of the application on the device.
 
  1. Return to Flash Builder and locate the BAR application package file in your project's bin-debug folder (see Figure 14 above). This is the debug version of the application installed on the device. You learn to create a release version of the BAR for distribution in the next section.
Step 14: Debug on a Blackberry Tablet OS device.
 
To debug an application on a device, you use Flash Builder to create, install, and launch a debug BAR package on the device just as you did for running the application on a device. For debugging, though, your computer and the device must be on the same Wi-Fi network. The USB cable is used to install the application on the device; the Wi-Fi network is used for all communication between the device and Flash Builder when the application is running and being debugged.
 
In Flash Builder, select your Blackberry Tablet OS device configuration profile from the drop-down menu for the Debug button. After the BAR package is created, it is installed and launched on the device and the Flash Builder debugger connects to the application running on the device. When a breakpoint in the code is reached, the application will freeze and you can use Flash Builder to step through code exactly as when using the Flash Builder device emulator or the BlackBerry Playbook Simulator.
 
If you have trouble debugging on the device, check to see if you computer is on a VPN and/or using a firewall. If the computer is on a VPN and the device is not, you may need to take the computer off the VPN for debugging to work. If you have a firewall turned on, try disabling it. If you cannot or do not want to disable it, try opening port 7935, the port used by the Flash Builder debugger to communicate with the device.
 

 
Package the application

When you have completed your testing and are ready to package the release version of the application for publishing on the BlackBerry App World, you use the Export Release Build wizard in Flash Builder.
 
Step 1: Set the application version.
 
Before packaging, you need to set the application's version number. The version number for a BlackBerry Tablet OS application is made up of a series of four numbers separated by decimals: (Major).(Minor).(Revision).(Build), for example 1.0.5.357. Each time you sign and package an application, you must change at least one segment of the version number. You can change the major, minor, and revision numbers by updating the versionNumber element in the application descriptor file. You can change the build number by updating the buildId element in the blackberry-tablet.xml file. It can be a number from 0 to 65535.
 
  1. Return to Flash Builder and open the application descriptor file.
  2. Set the versionNumber element (see Figure 40). This value must be updated for each release build you create.
  3. If you do not change the value from 0.0.0, you will get an invalid value error. If you try to package the application using a version number used to create a previous release build, you will get an error: Code signing request failed because this file has been previously signed.
Figure 40. Modify the application's version number.
Figure 40. Modify the application's version number.
 
Step 2: Set application properties.
 
If you have not done so already, set the application's id, name, application icon, and permissions. For details, refer to earlier steps 9–12 in the previous section.
 
Step 3: Export a release build.
 
Finally, generate a signed BAR file for distribution.
 
  1. Go to Project > Export Release Build and make sure BlackBerry Tablet OS platform is selected as a target platform and that Export signed packages for each target platform is selected; click Next (see Figure 41).
Figure 41. Create a release build.
Figure 41. Create a release build.
 
  1. On the Packaging Settings page, select Enable digital signing (see Figure 42).
Figure 42. Enable digital signing for the release build.
Figure 42. Enable digital signing for the release build.
 
  1. Click Finish. Flash Builder will create a BAR file for your application.
  2. Locate the release application package (see Figure 43).
Figure 43. Locate the release version of the application.
Figure 43. Locate the release version of the application.
 
  1. You can now submit this file to the Vendor Portal for BlackBerry App World for review by RIM. You can verify that a BAR file is signed appropriately by following the steps in this document.

 
Where to go from here

In this article, you learned to use Flash Builder and the BlackBerry Tablet OS SDK to run and debug Flex and ActionScript applications on BlackBerry Tablet OS devices. You also learned how to create a release build of your application for distribution. For more information, see the following resources:
 
Adobe websites:
 
RIM websites: