Home / Tutorials /

10 Easy Steps to Package and Sign AIR Apps for PlayBook

Packaging for BlackBerry PlayBookIt 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: -

  1. Application Descriptor XML (game-app.xml)
  2. Icon file that goes on the tablet’s applications screen (icon.png)
  3. A splash screen PNG file that appears before the actual swf is executed in the tablet (splash.png)
  4. 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: -

Download BlackBerry Tablet OS SDK

Installing the SDK should dump the SDK into a folder name similar to – “blackberry-tablet-sdk-0.9.3″. These are the folder contents: -

SDK Installed Folder


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.

Folder before packaging


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: -

Icon and Splash

<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

Command: Create .bar package

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.

PIN

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

Command: Create .csk file

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 -

Mac:

~/user/Library/Research In Motion/barsigner.csk

Win:

\Document and Settings\<name>\Local Settings\Application Data\Research In Motion\barsigner.csk

or

\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: -

blackberry-signer -cskdelete

Command: Delete .csk file


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

Command: Register with RIM

Once you get this message, you should also have received a confirmation email from “websigner@ws-smtp.rim.net” 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.

Command: Create p12 Certificate


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.

Command: Sign .bar file by RIM

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.

Command: Sign .bar file by author

This signs the .bar file again.


Conclusion

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… :)

Happy packaging!


UPDATE:

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.


  • Eric Holm

    Great tutorial really useful.

    The only problem I encountered on Mac OS X 10.6 was a problem with running the ‘blackberry-signer’.
    When I moved to the directory and tried to run ‘blackberry-signer’ it didn’t worked, but it did work with ‘./blackberry-signer’.

    So you need a ‘dot’ and a ‘forward slash’ in front when u use mac os x.

  • Divakarla Srinivas

    Thanks a ton… it helped me a lot ….
    any plans to have a developer summit for playbook?? in bangalore??

  • CrookedAlley

    Thanks so much, it was a great help!!

  • Manikantan Krishnamurthy

    Hi hemanth,
    I am getting an error saying invalid option -csjpin in step 8.

    “Barsigner error : illegal option -csjpin ”

    Can you tell me where I am going wrong ?

  • http://www.hsharma.com Hemanth Sharma

    Manikantan,

    Be sure you are trying to enter the same CSJ PIN you entered in Step 6. Also note that all your capital alphabets will be converted to small in Step 6. So, you will need to enter small case alphabets in Step 8.

    If this doesn’t solve, could you also paste the exact error message and the command you typed?

    - h

  • Pingback: Blackberry Playbook, Flash, AIR etc « My Adobe Flash Tech Blog

  • http://www.zgflex.org Ivan Ilijasic

    @Manikantan, are you sure you’re using CSJ pin identical to the one you entered when you made a certificate file request. That was my problem and since you have only 5 attempts (at least I think this is the right number) to enter correct pin, after five times your certificate will be deactivated. That was my problem and after that I didn’t contact RIM support, I just ordered new certificate.

    @Hemanth, thanks for an excellent article. You made some things some much clearer and I suggest you to submit your text to BlackBerry or on Devnet because BB’s instructions are not easy to read, especially if you are not experienced with RIM’s way of handling app releases. While I was reading the instructions published on BB pages, I thought that RIM Signing Authority is a person or an online application or some IT team that I have to contact via email :)

    Your article is much easier to read and now I fully understand how to handle app signing by using command line or FB.

    Take care,
    Ivan

  • http://www.hsharma.com Hemanth Sharma

    Ivan,

    Thanks for your kind words… That is really encouraging. :)

    - h

  • Mohammed Kayyali

    Do i MUST to sign application before submit it ? or i can sign it after approval ?? Thanks…

  • http://www.hsharma.com Hemanth Sharma

    Mohammed, you need to sign it before submitting/approval.

    - h

  • Mohammed Kayyali

    Thank you :) another question sorry :(

    in the vendor information there is no company name to use it in developer certificate, only vendor name and the reset info, do i have to use vendor name as company name ?

  • http://www.hsharma.com Hemanth Sharma

    I have done the same thing Mohammed. I hope you are right.

    - h

  • Aran Rhee

    Great article.

    It got me up and happening to sign my app without errors even for a terminal novice like myself.

    Cheers.

  • http://www.zgflex.org Ivan Ilijasic

    One more detail – during my signing process I received an error that I have to define an icon 57×57 in my blackberry-tablet.xml. Naturally, I had to create an image file for this purpose :)

    @Mohammed, I used my own name (since I published app under my name) and everything went just fine.

  • http://www.hsharma.com Hemanth Sharma

    Thank you Aran and all. I am glad I could be of help.

    - h

  • andybrandy

    hi, thx – this helps so much!
    in step 10 i ran into the this error in the first signing:

    “Invalid value ’1.0.0.0′ for Application-Requires-System.”

    i googled an hour but still no clear answer? can anybody help?
    thx

  • andybrandy

    ok – sorry for my first post – i was in the 0.9.2 bin directory.
    now iam in the 9.3: but next problem: i deleted my first CSK file and generated a new one with the 9.3 bin files and now in step 10 i got this error:

    barsigner error: Certificate chain not found for: RDK. RDK must reference a valid KeyStore key entry containing a private key and corresponding public key certificate chain.

    is this because i deleted the first CSK file?
    help? please ;)

  • http://www.hsharma.com Hemanth Sharma

    Andy, I am guessing this is something to do with wrong password. I have not faced this situation though.

    Also make sure you haven’t left out any required parameters. -storepass is critical in this statement and may lead to such an error.

    - h

  • Matt

    Very helpful. Thanks for putting this together. This is unbelievably cumbersome. If Blackberry wants developers for their new device they’ll need to overhaul this process.

  • http://www.hsharma.com Hemanth Sharma

    @Matt, :)

    - h

  • Pingback: Tricky end-game of signing your apps | roguish

  • http://flexoop.com Gareth Arch

    Not sure why, but when I follow the above steps, I get the correct files in my bar file, but when I go to install and deploy on the playbook simulator, the icon shows up correctly, it says that the app is loading, but then it fails and returns to the main screen (and replaces the top nav bar on the playbook that has the time on it with a white bar). However, when I export a release build via FB Burrito, and I do a command line install, it opens correctly and works fine (but the .bar file only contains MANIFEST.MF and the AIR files)

    I’m using the same files for both, but the “correctly” signed app does not open. Any ideas what’s going wrong, or what I can add to either debug the production app better or see what’s going wrong when it is opened?

  • http://flexoop.com Gareth Arch

    Turns out I hadn’t added -debug=false to my compiler arguments (not really stated anywhere and FB barks at you that it doesn’t do anything to add -debug to compiler arguments…but apparently it does)

  • http://www.hsharma.com Hemanth Sharma

    Not sure Gareth… Haven’t faced the situation. If you find it, I request you to post it here so others who have the same problem can be helped.

    - h

  • http://flexoop.com Gareth Arch

    @Hemanth,
    Yeah, that’s what my follow up post was about :) I added
    -debug=false
    to my compiler arguments and that seems to have fixed the problem. The swf created is then ready for export as a production app rather than a debug app. I also posted to the forums at BlackBerry so hopefully RIM will update the docs

  • http://www.hsharma.com Hemanth Sharma

    That’s cool Gareth… Thank you :)

    - h

  • Svend

    Hi,

    Just a side note on CSJ PIN: on creation, the RIM web site requires you to enter a 6-10 lowercase alphanumeric string.

    I erroneously provided a PIN containing uppercase characters, WHICH HAVE BEEN ACCEPTED AND SILENTLY TURNED INTO LOWERCASE by the system!

    => when trying to register my RIM certificate, it took me some trials before understand that and adapting my PIN.

    Ok, the original mistake is on my side, still I would expect the web site to warn me

    (shhhh, I must be part of the *assisted generation*, old timer ASM developers would smile at my “problem” I guess…)

  • http://www.hsharma.com Hemanth Sharma

    Yes Svend, I had mentioned the point in step 6 (underlined). :)

    - h

  • http://starpause.com/ starpause

    THANKS for the clear guide! I had an issue when attempting to sign with 0.9.2 SDK, then I upgraded to 0.9.4 SDK and all went without a hitch.

  • Dany

    Thats is the best tutorial i have found, thank you so much.

  • Damian

    Hi Hemanth,

    Many thanks for this. Much clearer than the official RIM instructions!
    I get to Step 9 OK then get an error message.

    The command I type at this step is:
    blackberry-keytool -genkeypair -keystore damiansHockeyCert.p12 -storepass itmasppal -dname “cn=NA” -alias author

    The error message I get back is:
    keytool error: java.io.FileNotFoundException: damiansHockeyCert.p12 (access is denied)

    Do you know why I might be getting this?

    Thanks in advance.

    Damian

  • Damian

    Hi Again Hemanth,

    I managed to fix my problem at Step 9. Something to do with not having full write permission in the directory I was trying to create the .p12 file in.

    Now I’m stuck at the first part of Step 10 :(

    I type in the following:
    blackberry-signer -verbose -cskpass xxxxxxxx -keystore damiansHockeyCert.p12 -storepass xxxxxxx main7.bar RDK
    (Obviously in place of the x’s I use my passwords)

    I get the following error message:
    barsigner error: Certificate chain not found for: RDK RDK must reference a valid Keystore key entry containing a private key and a corresponding public key certificate chain.

    Any help would be appreciated!

    Thanks again!

    Damian

  • yincan

    Thanks hemanth, do you have a apache-ant-build-script for these steps :)

  • http://www.hsharma.com Hemanth Sharma

    No @yincan…

    - h

  • Pingback: Building a jQuery Mobile Application with the PlayBook WebWorks SDK : Ryan Stewart – Mountaineer Coding

  • Damian

    Hi Again,

    Just tried to sign again with new keys & finally got it to work.
    I suspect my problem was related to doing the commands in the wrong directories.
    Thanks for the clear instructions!

    Damian.

  • http://www.hsharma.com Hemanth Sharma

    Damian,

    All the best… :)

    - h

  • Pingback: Building a jQuery Mobile Application with the PlayBook WebWorks SDK (Adobe Flash Platform Blog)

  • James

    I’m also getting this error:

    Certificate chain not found for: RDK. RDK must reference a valid KeyStore key entry containing a private key and corresponding public key certificate chain.

    I see couple of other people are getting the same error… Anyone got the solution yet?

  • http://www.hsharma.com Hemanth Sharma

    James, I haven’t faced this issue… Guessing it is the wrong password. Not sure though. CSJ pwd is all small-case. If you somehow find a solution, do post it here. Thanks…

    - h

  • http://www.mellisdesigns.com Mitch Ellis

    Hey Guys

    If blackberry ask you to make a few changes, how do you resubmit your app? Do you have to go through the whole signing process again? Does anyone know where I can find info on this?

  • http://www.hsharma.com Hemanth Sharma

    Hi Mitch,

    Yes. If it is changes in the application, you will naturally make changes in the code, then re-package it. Once you re-package it, you will have to re-sign it. Make sure your revision version is atleast incremented (e.g., 1.0.1 from 1.0.0). You cannot sign the already signed version. Follow this tutorial to sign it again.

    - h

  • http://www.svemir.net Tomislav Pokrajcic

    Hemanth tanks for a great article, it helped a lot. However the signing process still succeeded in driving us mad :)
    In the last step we were getting “already signed” error although we raised release version to 1.0.1.
    It seems that during our trying process we once executed last step with bad certificates (or some other error that prevented successful signing) but RIM server remembered 1.0.1 version as used anyway.
    So we lost hours in trying to detect the problem until we raised the version again to 1.0.2 and then the magic happened.
    Hope the tip can help to someone else.
    Cheers,

    Tomislav

  • http://www.mellisdesigns.com Mitch Ellis

    Hey Hemanth

    Thanks for the reply, So i would assume that because I have already used the CSJ file from blackberry, I have to order another CSJ file to resign the changed version? My problem is that when I run the
    “blackberry-signer -register” command it tells me my csj file is already registered, thus when I try and run the first signing of the application “blackberry-signer -verbose” I also get an error from the RIM server.

    I did get some weird result saying that my app needed to make the following amendments, -No icon, and icon name is misspelled.

    I checked the whole package file and everything seems to be ok, anyway I have basically gone through everything and double double checked, made some slight changes.

  • http://www.hsharma.com Hemanth Sharma

    Hi Mitch,

    Don’t follow all the steps to re-sign. You need a certificate (.p12) to sign a package. You got it. You need to first time register the certificate (until Step 9). You have done it.

    Now, to re-package the edited app, follow Step 1 to Step 5 to re-sign a new package, just follow from Step 10 onwards. Don’t repeat Step 8 or 9. You should just be fine.

    - h

  • http://www.hsharma.com Hemanth Sharma

    Hi Tomislav,

    Am glad it worked… All the best.

    - h

  • http://www.mellisdesigns.com Mitch Ellis

    Hey Hemanth

    Unfortunately at step 10, the first command:

    blackberry-signer -verbose -cskpass CSKPassword -keystore CertificateName.p12 -storepass StorePassword BarFileNameForRIMToSign.bar RDK

    gives me the error Certificate Chain not found for: RDK. RDK must reference a valid keystore key entry containing a private key and corresponding public key certificate chain.

    This is the only spot I am stuck at. I am able to sign for myself but I am unable to sign with RIM.

  • http://www.hsharma.com Hemanth Sharma

    Mitch,

    I am unsure about it. You might have to retry by making sure the StorePassword in your statement is precise. Some of others have also faced the same problem. I haven’t come across that issue.

    - h

  • http://www.mellisdesigns.com Mitch Ellis

    Thanks Hemanth

    By the way you blog is amazing, and you have helped a lot of developers out there! Love your work man!

    Best Regards!
    Mitch

  • http://www.hsharma.com Hemanth Sharma

    Hey thanks a lot Mitch!

    - h