It has become a little obvious that the packaging, signing and publishing to BlackBerry PlayBook is a little difficult process. Yes, it took me a while to figure out how to do it. Had to browse through a lot of documentation to understand the process.
Thought of writing a simpler, straight forward post that will explain and show how to do the same in easy steps (for those who don’t want to spend more time understanding every aspect of it).
Assuming the AIR app is built using Flash Professional CS5 (that’s what I did), I am using command-line tools to get through this process. So, it is also obvious that this process is for pure ActionScript projects.
The screenshots of the Terminal window that you see in this tutorial are the actual screenshots I took. I wrote this tutorial first and then followed the commands I have mentioned myself and took the screenshots. I also didn’t get any errors following this. So, I am pretty sure this process works.
Publish the SWF file
First, have the .SWF file published.
Have the resources ready
Now, you will need 4 files to create a nice package: -
- Application Descriptor XML (game-app.xml)
- Icon file that goes on the tablet’s applications screen (icon.png)
- A splash screen PNG file that appears before the actual swf is executed in the tablet (splash.png)
- Icon and Splash screen mentioned in an XML (blackberry-tablet.xml)
Step 1: Download and install the SDK
Download and install the BlackBerry Tablet OS SDK for Adobe AIR from – http://us.blackberry.com/developers/tablet/adobe.jsp
I have not covered the installation, setup and execution of the simulator in this post. Therefore, I will just mention the steps required to install the SDK, create package and sign the package. The link to download the SDK should be similar to the image below for your respective platforms: -
Installing the SDK should dump the SDK into a folder name similar to – “blackberry-tablet-sdk-0.9.3″. These are the folder contents: -
Step 2: Just before packaging
This is how my directory looks before I start packaging. It contains the resources mentioned in Step 1 and the downloaded SDK.
Step 3: Create the blackberry-tablet.xml
This XML file contains the icon and splash screen that need to appear on your tablet’s applications screen and just before opening the application respectively. Below is the screenshot that shows the appeared icon_86.png and crazygems-splash.jpg used in blackberry-tablet.xml: -
<qnx> <initialWindow> <systemChrome>none</systemChrome> <transparent>false</transparent> </initialWindow> <publisher>hsharma.com</publisher> <category>core.games</category> <icon> <image>Icon_86.png</image> </icon> <splashscreen>crazygems-splash.jpg</splashscreen> </qnx>
Step 4: Create the Application Descriptor XML (CrazyGems-app.xml)
This is by default generated by Flash Pro when your publish settings is set to AIR 2.5. I have made minor changes that restrict the orientation to landscape only.
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <application xmlns="http://ns.adobe.com/air/application/2.5"> <id>com.hsharma.crazygems2</id> <versionNumber>2.1.0</versionNumber> <filename>Crazy Gems 2</filename> <description>Crazy Gems 2.1</description> <name>Crazy Gems 2</name> <copyright>http://www.hsharma.com/projects/crazygems2</copyright> <initialWindow> <content>CrazyGems.swf</content> <systemChrome>standard</systemChrome> <transparent>false</transparent> <visible>true</visible> <fullScreen>false</fullScreen> <autoOrients>false</autoOrients> <aspectRatio>landscape</aspectRatio> <renderMode>auto</renderMode> <maximizable>false</maximizable> <minimizable>true</minimizable> <resizable>false</resizable> </initialWindow> <customUpdateUI>false</customUpdateUI> <allowBrowserInvocation>false</allowBrowserInvocation> </application>
Step 5: Create the .bar package
This is the simple command that is used to package the .swf and other resources into .bar. Note: The packaging and signing tools are in the subfolder “bin” under the SDK folder.
blackberry-airpackager -package DesiredPackageName.bar game-app.xml blackberry-tablet.xml GameOrApp.swf IconFile86x86.png AllOtherFilesRequiredByYourSwf SplashScreen.png
Note that all the text in red needs to be replaced with the files that you prepared in Step 1. SplashScreen.png and IconFile86x86.png refers to the files included in the blackberry-tablet.xml file in Step 3.
AllOtherFilesRequiredByYourSwf parameter in the above command is where we need to specify all files that are required by the app .swf in runtime. These filenames should be separated by spaces. Also, don’t forget to copy the files in the same folder as .swf.
Now, using this command to actually package my game, looks like this: -
blackberry-airpackager -package CrazyGems2.bar CrazyGems-app.xml blackberry-tablet.xml CrazyGems.swf Icon_86.png crazygems-splash.jpg
This generates the desired CrazyGems2.bar file.
I have ignored -launchApp, -installApp and -device and -password parameters of command-line as they are for running and testing the app on the PlayBook or simulator.
Step 6: Preparing for signing
To sign your package, you will need a signing key from BlackBerry. You can request for the same from https://www.blackberry.com/SignedKeys/.
In this process, please keep in mind that the PIN you enter in the field shown below is extremely important. Do not forget this. Also, note that this PIN allows alpha-numeric characters. The catch is, the alphabets used will be forced to small-case.
You will receive a .CSJ file in a couple of days from BlackBerry.
Step 7: Creating the CSK file
Once you receive the .CSJ file and you are ready to sign, you will need to open Command Prompt (Windows) or Terminal (Mac).
Make sure you change directory to the one where your SDK is copied. Enter the following command to create a .csk file: -
blackberry-signer -csksetup -cskpass DesiredCSKPassword
Again, text in red is what you need to fill in with your information. Enter the desired password for csk file. This password will be used in just a bit. Also, the file created won’t be in the same folder. This is created in -
~/user/Library/Research In Motion/barsigner.csk
\Document and Settings\<name>\Local Settings\Application Data\Research In Motion\barsigner.csk
\Users\Youraccount\AppData\Local\Research In Motion\barsigner.csk
Deleting the CSK (just in case)
If you have already created a .csk and want to delete it, use the command below: -
Step 8: Register with RIM Server
Now, you need to register with RIM Server using the .csj file. Run the following command: -
blackberry-signer -register -csjpin PinYouEnteredWhileRequestingCSJ -cskpass PasswordYouEnteredWhileGeneratingCSK client-RDK-XXXXXXXXXX.csj
PinYouEnteredWhileRegisteringCSJ – is the one you entered by choice in Step 6.
PasswordYouEnteredWhileGeneratingCSK – is the one you entered by choice in Step 7.
Once you submit, you should see the response – “Successfully registered with server.”
Once you get this message, you should also have received a confirmation email from “firstname.lastname@example.org” with the subject “Successful Registration Request for Client ’1279793156′”.
Step 9: Create the .p12 Certificate
Once you have registered with RIM server, you can generate the .p12 certificate required to sign your .bar file package. Finally… eh? Not yet actually… Signing in next step.
blackberry-keytool -genkeypair -keystore DesiredCertificateName.p12 -storepass NewPassword -dname "cn=YourCompanyName" -alias author
Make sure you modify only the red text in the above command.
YourCompanyName can contain spaces and full-stop. But not comma.
Step 10: Sign the package with the .p12 Certificate
Finally, we are now ready to sign the package we created in Step 7. Note that you will need to sign the .bar file twice. Once from RIM and once from you as an author.
Use the below command to sign the .bar file first time: -
blackberry-signer -verbose -cskpass CSKPassword -keystore CertificateName.p12 -storepass StorePassword BarFileNameForRIMToSign.bar RDK
CSKPassword – from Step 7.
CertificateName – from Step 9.
StorePassword – This is the
NewPassword from Step 9.
BarFileNameForRIMToSign.bar – The .bar file created in Step 5.
Now, sign the already signed file. The first time you signed, was from RIM. Now you sign from the author’s (your) side.
blackberry-signer -keystore CertificateName.p12 -storepass StorePassword RimSignedBarFile.bar author
CertificateName – from Step 9.
StorePassword – This is the
NewPassword from Step 9.
RimSignedBarFile.bar – The .bar file created in Step 5 and signed in Step 10 in previous command.
This signs the .bar file again.
So, here you go. You should have a final .bar file that is ready to be published on the BlackBerry App World. Please do write back if you find issues. I will try my best to point you to a possible solution or place where you can find one…
If you get an error “Code signing request failed because this file has been previously signed.” when you try to sign a new package (probably not a major change) with same name and version for your app, change the <versionNumber>x.y.z</versionNumber> tag (line 4) in Step 4. Good idea to increment “z” in the version (revision version). Then try to repackage and it should work.