Looking back during the early days of my involvement in this, I kept telling myself, “how hard can it be?” As you may know, RIM is almost the new kids on the block in the Tablet race game for 2011, which suffers a lot of criticism for not having a lot of app compared to its competitor, which is also true for Android, prior to launch previously. Give this platform a try, and you will know how much RIM has poured their trust and appreciation for Flash developer in this manner. And it is definitely not the developing for Android where you will still need to install the AIR player separately (which is EXTREMELY lame). The PlayBook has AIR integrated into its CORE OS, which means, you can get every single PlayBook on the planet to run your app without any extra installation.
Why is this post relevant to you? I’m pretty sure you might stumble across this infamous blog post: You Win! RIM by Jamie Murai. Certainly, RIM did listened to the rants and frustration of developer and evolved overtime to remedy their over-complicated process. Few months have passed since then, and I can’t tell how much I’m thankful to RIM for its appreciation for developer, and especially the Flash platform. I’m here, happy with my PlayBook (from the Free PlayBook offer) going to share with you the entire workflow and process, which afterall, is not as scary as it seems, but in fact, has toned down a lot more compared to the earlier days. Sure, you might argue Apple has the best submission mechanism and workflow in the world, but that does not happen overnight, neither do Android Market.
This will be the definitive guide for Mac users with Adobe Flash Professional to creating their PlayBook app. To give you an idea on how much time and effort you need to spend from developing to submitting an app to AppWorld, in point forms below, the 5 steps to your first app in AppWorld.
- Downloads (1 day)
- Apply as vendor (may take up to 3 working days for vendor application & code signing keys approval)
- Simulator and development (minimum 1 day, varies depending on complexity of your app)
- Signing your app (for submission to AppWorld) (1 day)
- Waiting for review and putting app on sale (7 – 14 days)
In this guide, we will assume that you are running the setup below:
- A Mac user
- Flash Professional (sorry Flash Builders :P)
- Have no access to the real device, hence using the simulator
First up, we need to download the files below to get started.
Image shown above on files needed for the entire development. It is not necessary for you to donwload the Simulator ISO as it is already bundled in the Tablet SDK. I downloaded it because I was having some weird problem on my machine at that time.
The entire downloading process shouldn’t take more than half a day, depending your internet connection speed.
The link and image above will direct you to the main resources page that highlights every necessary steps to get started, however it is still lacking what this guide could provide.
2. VENDOR & KEY APPLICATION
There will be 2 type of online form that you will ever need to fill up.
- The Code Signing Key application form
- The vendor application form
Click on the link above to get to the application form. Please remember to write down the Company Name used in this form. If you submitted the request with the company name of “My Company Name”, you will need to stick with it.
Once you have submitted the form, you will receive a confirmation from RIM. You will need to wait at least 2 working days for RIM to respond to you on this matter. Look at the screenshot below on what email you will be expecting from them.
Shown above is the email attached with a .CSJ file. We will only be using this file ONCE for configuring (authorizing) our machine for app submission.
The second form we will ever need to fill up is the vendor application form, allowing us to have an account in AppWorld. Check out my account on AppWorld.
Once you have submitted the form, you will receive this confirmation email. Look at the image below on what type of email you will anticipate next from RIM.
Approximately after 2 working days, you will receive an email asking you to submit documentation for verification. For individual developer, the requirement has been toned down which you can submit a scanned image of your identification card of country of residency.
After completing the documentation submission to RIM, allow up to 5 working days for them to do verifiction, the process might be faster now.
3. SIMULATOR & DEVELOPMENT
While waiting for the application form to be processed, you can take your time in setting up your working environment and start working on your app. Before moving on with development, we will start with installing the simulator, and running it through VMWare Fusion 3 (Mac).
Setting up Simulator & SDK
Before installing VMWare Fusion on your mac, grab a 30-days trial license from VMWare. You will receive an email as above after going through some troublesome but necessary process in obtaining the license key.
Unzip the Tablet OS SDK and run the installation.
You will then asked if you want to integrate the Tablet OS SDK with Flash Builder, select NO.
Choose a custom folder to install this, create your own working folder, and select that.
Since we are not using Flash Builder, unzip both file to your development folder (i.e. Desktop). During the installation of the Tablet OS SDK, you will be asked for the location of your AIR SDK,
Above is the my working folders. As you can see, I have the an independent SDK folder which can be used during app compiling/signing. The pros of having this is I can move the folder anywhere I want, without being restricted by an installed software (i.e. Flash Builder), afraid that it will not after I had changed the location of the SDK.
If your setup runs correctly, you should see the SDK folder filled with files as per screenshot below (combination between Tablet OS SDK and AIR SDK).
Install VMWare fusion, and set up the Simulator. (Make sure the RAM is set to 1024MB) Once installation of VMWare is succesful, go to Open and navigate to your SDK folder and select BlackBerryPlayBookSimulator.vmx inside the folder BlackberryPlayBookSimulator-1.0.1. Your simulator is now ready to run. No extra installation is necessary.
Once setup correctly, you should see the above screen.
A look at the simulator running. As you can see there is a huge black border around the screen, it is not an error but intentional. The black border is mouse reactive which you can slide from the border into the screen to activate actions.
In order for us to install our app onto the simulator. We need to:
- Set the simulator run in DEVELOPMENT MODE
- Get the IP of the simulator (after setting it to development mode)
- Upload debug token on the simulator
To get started, click on the Gear icon on the top right to access the Settings menu.
From the Settings men, click on Security and then Password. Set a password. Go back to the main Security settings, select Development mode.
Enable development mode, you will be prompted to enter the password that you have just defined.As shown on the image, a debug token has been added into the simulator, but I will cover on that later when we are ready to install app onto the simulator.
Setting up Development
Few tips in developing an App for Blackberry PlayBook.
- Stage size is set at 1024 x 768
- Frame rate at 24 fps is more than sufficient for you to get started
- You need a descriptor file named blackberry-tablet.xml (more on this later)
- You need an icon file at 86 x 86 pixel
- You need a splash image at 1024 x 600
- If you are on Flash Professional CS5, set your target build to AIR 2.5
- For PlayBook apps, it is mandatory for you to have the version number format as 1.0.0 (3 digits?) instead of the usual 1.0 formatting, which you might end up like 1.0.0, 1.0.1 and so on.
- We will be using Terminal in Mac OSX to do our app packaging most of the time, do not fret, it will be like a walk in the park.
The infamous blackberry-tablet.xml, if you want to know how to set up this file, a page dedicated for this, and different type of permission can be read at http://docs.blackberry.com/en/developers/deliverables/23959/Configuring_your_application_1524626_11.jsp.
What about using Terminal? How can a designer, like me, can get used to typing command lines, and remembering all the parameters needed for app packaging? Courtesy from the Adobe Refresh conference, learned a trick which you can have a TextEdit file (text field) to store all the information in one place.
As you can see from the screenshot above, it contains every single essential command line that I can just copy and paste it in Terminal, almost effortlessly. Hence, I would strongly suggest for you to have a text file to keep all your commands in one place. I named it commands.rtf.
Setting up design assets, screenshot, icon, product icon, sound, description, SKU
The next in the checklist for submission, you will need:
- A product icon sized at 480 x 480
- Screenshot of your app, sized at 640 x 375 (resized from 1024 x 600), minimum 1
- Title of your app
- Description of your app
Packaging an app for Blackberry Playbook
It is easy to package your swf (AIR) files into playbook app, known as BAR file (.bar extension). In this guide, I will assume that we will copy all of our files for app packaging in the same folder as the packager located at (YOUR SDK FOLDER)/bin/ (look at screenshot above).
The command to create a BAR file that can be tested inside the simulator is as below:
blackberry-airpackager -package YOUR_BAR_FILE.bar main-app.xml main.swf blackberry-tablet.xml YOUR_ICON.png YOUR_SPLASH_IMAGE.png -devMode
Shown above is an example of a BAR file successfully created. Notice the -devMode parameter. It is really important to include that for testing purpose. We are now ready to install and launch our app inside the simulator.
Testing on simulator, using debug token
Before you can install and test your app on the simulator, we will need to “upload” (install) a debug token on it.
First and foremost, we will need to obtain the simulator’s Device ID, by going into Settings, then About, and on the dropdown menu, select Hardware. Look at PIN.If the PIN is FFFFA364, then your Device ID will be 0xFFFFA364 (add the 0x prefix).
Next, we will get the Device’s IP address, by clicking on the User icon (with gears in it), which will be accessible when the simulator is set to Development Mode.
We will now have to go through 7 steps, with 5 of it only needed to be done once from setting up, to finally install and launch our app:
- A. Create CSK file
- B. Sending CSK & CSJ information to AppWorld for authorisation
- C. Create a developer certificate (p.12 file)
- D. Create Debug Token (for the current development machine)
- E. Create Debug Token for simulator
- F. Install Debug Token
- G. Install and Launch app
A. Create CSK file (only needed to be done once)
blackberry-signer -csksetup -cskpass CSK_PASSWORD
B. Sending CSK & CSJ information to AppWorld (only needed to be done once)
blackberry-signer -register -csjpin CSJ_PIN -cskpass CSK_PASSWORD YOUR_CSJ_FILE.csj
C. Create a developer certificate (Only needed to be done once)
blackberry-keytool -genkeypair -keystore YOUR_FILENAME.p12 -storepass YOUR_P12_PASSWORD -dname “cn=COMPANY_NAME_AS_REGISTERED_FOR_CSK” -alias author
D. Create Debug Token (This only needed to be done once)
blackberry-debugtokenrequest -register -cskpass CSK_PASSWORD -csjpin CSJ_PIN_NUMBER YOUR_CSJ_FILE.csj
E. Create Debug Token for simulator
blackberry-debugtokenrequest -cskpass CSK_PASSWORD -keystore YOUR_P12_CERTIFICATE.p12 -storepass P12_CERTIFICATE_PASSWORD -deviceId YOUR_DEVICE_ID YOUR_BAR_FILE.bar
F. Install debug token into simulator
blackberry-deploy -installDebugToken YOUR_BAR_FILE.bar -device DEVICE_IP -password YOUR_DEVICE_PASSWORD
G. Install and launch app
blackberry-deploy -package YOUR_BAR_FILE.bar -installApp -launchApp -device DEVICE_IP -password YOUR_DEVICE_PASSWORD
H. To delete an app (this will only work if your BAR file still remains inside the sdk folder)
blackberry-deploy -package YOUR_BAR_FILE.bar -uninstallApp -device DEVICE_IP -password YOUR_DEVICE_PASSWORD
Shown above is a message returned when your BAR file is valid. “The bar manifst file is valid.”
Shown above is when the BAR file is successfully installed on the simulator, and are preparing to launch the app.
This is how it looks like, with my app running inside the simulator.
Above is a screenshot on what your user will be seeing, a special permission alert window if your app is accessing the Camera, Geolocation or even stored files.
4. SIGNING APP FOR SUBMISSION
And now that you are have completed the development of your app and are pretty sure that you want to submit your app. There will essentially be 3 steps to this:
- A. Package your app file into BAR file (without -devMode)
- B. Sign your BAR file by RIM
- C. Sign your BAR file
A. Package your app file into BAR file
blackberry-airpackager -package YOUR_BAR_FILE.bar main-app.xml main.swf blackberry-tablet.xml YOUR_ICON.png YOUR_SPLASH_IMAGE.png
B. Sign your BAR file by RIM
blackberry-signer -verbose -cskpass CSK_PASSWORD -keystore YOUR_P12_CERTIFICATE.p12 -storepass P12_CERTIFICATE_PASSWORD YOUR_BAR_FILE.bar RDK
C. Sign your BAR file
blackberry-signer -keystore YOUR_P12_CERTIFICATE.p12 -storepass P12_CERTIFICATE_PASSWORD YOUR_BAR_FILE.bar author
When you first sent the signing command to RIM (Step B), you will see a lot of code/gibberish running.
And when it is done, you will be told that it is succesfully signed.
When step C is completed as well, you will also see a confirmation that your file is signed. Once the steps are all completed, you are now eligible to submit your signed app to the AppWorld. Although it would be really hard to gauge if your app is really signed. But you will notice there will be an increase in the BAR’s filesize.
5. SUBMISSION & REVIEW PROCESS
To submit an app, login to: https://appworld.blackberry.com/isvportal
You can rest assure that the process of app submission in AppWorld will be a breeze. Once your app is submitted, allow up to 2 weeks for review process to take place.
Once your app is approved, you should receive an email as above.
With all the hard work completed, your app will then appear on the AppWorld. Congratulations!
6. USEFUL LINKS
- Tablet OS SDK for Adobe AIR
A great place to hang out with other AIR developers. You will get insights and tips on the tablet development.
- Crackberry’s PlayBook Apps & Games
A great place to check out other PlayBook apps, which you can showcase yours, or ask for reviews.
Last updated: May 14, 2011