Marmalade SDK and Blackberry Playbook – From Setup and Deployment to App World Submission

The latest version of the marvellous Marmalade SDK 5.1.3 has recently hit our development machines. Whats so special about 5.1.3 you ask? Well for starters you can now deploy your smart phone and tablet apps and games to the awesome Blackberry Playbook. If you haven’t had the chance to tinker with one of these beauties then I suggest you go and have a play because they are fantastic tablets. Amazon are selling them right now here for 16GB version and here for 64GB version

Ok you read this far and thought, “hmm, what the hell is the Marmalade SDK fool?”, sounds like something you would spread on toast and not actually use to make ground breaking cross platform games and apps. For those developers that have been asleep for the last couple of years or maybe just missed the name change, the Marmalade SDK is the newly named AirPlay SDK created by the boffins over at IdeaWorks. The marmalade SDK is basically an awesome system that allows developers to develop apps and games using a single unified API for a whole host of platforms including Apple iPhone, iPad, Android phones & tablets, Samsung Bada, Blackberry Playbook, Web OS, Symbian, Windows Mobile, Windows, Mac and others. How do they do that you may ask, well don’t ask me! take a trip over to http://www.madewithmarmalade.com and take a look

Ok, shameless plug for my favourite SDK of all time out of the way, now on with the article

We have recently just ported one of our games “BattleBallz Chaos” to the Blackberry Playbook platform and had it published in record time (for our company at least). Within 24 hours we went from receiving our Blackberry Playbook test tablet and our unified Android, iOS, Bada code base to “on the App World store!” For those interested you can check out BattleBallz Chaos here and more info about our other versions for iPhone, iPad, Android, Bada and Windows Phone 7 is at http://www.battleballz.com

BattleBallz Chaos Blackberry Playbook Screen Shot
BattleBallz Chaos in action on the Blackberry Playbook

You are probably here because you are pulling your hair out trying to accomplish one of the following:

  • Deploy a debug build to an actual Blackberry Playbook tablet
  • Having trouble getting your build ready for submission to RIM’s Blackberry App World store
  • Need to know the splash screen, icon formats and sizes for a Blackberry Playbook build
  • Other random issues with Marmalade or Blackberry Playbook deployment or submissions

Well for whatever reason I hope this article can help you in some small way, now on with the article

Preparing your system

1. Grab a copy of the Blackberry Web Works SDK from http://us.blackberry.com/developers/tablet/webworks.jsp. Note that you will also have some other tools to install which are listed on that same page, just follow the instructions
2. Install the SDK to your development machine as specified

You may be wondering why you would need to install the HTML5 SDK when you are deploying a native application. The reason is that you need the binary tools that are located in this SDK. Note that the native SDK is Beta at the moment and is only available by asking Blackberry directly for access to the beta program at http://03268fe.netsolhost.com/bbbeta/

Set up your PC to allow signing with the Blackberry signing server: (Only has to be done once)

3. Go to Blackberrys online code signing keys request tool at https://www.blackberry.com/SignedKeys/, fill in the information and submit,. You will be emailed 2 registration files that look something like this (DONT FORGET YOUR PIN!):

  • client-RDK-195133201.csj – This is for the signing process (RBK)
  • client-PBDT-195133201.csj – This is for the debug token creation process (PBDT)

NOTE: It may take a few days to get the registration files so apply for them immediately

4. Now lets actually do the set-up process

* Copy the registration files from step 3 into a folder (lets call it ‘Playbook’)
* Open up a command prompt and change to the ‘Playbook’ folder you just created
* Run the following commands at the command prompt:

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-keytool" -genkeypair -keystore sigtool.p12 –storepass {your_password} -dname "cn={your_company_name}" -alias author
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -csksetup -cskpass {your_password}
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -register –csjpin {your_pin} -cskpass {your_password} client-RDK-195133201.csj

{your_password} – Choose a password that you are going to remember
{your_company_name} – Company name as specified when you requested the registration files in step 3
{your_pin} – The pin you created when you requested the registration files in step 3
client-RDK-195133201.csj – Change this to the name of the RDK CSJ file that you received in your registration files email in step 2

NOTE: The location where the blackberry-keytool and blackberry-signer will probably be different depending on which SDK you are using and where you installed it

Set up your PC to enable generation of debug tokens (Only has to be done once)

5. Open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-debugtokenrequest.bat" -register -cskpass {your_password} -csjpin {your_pin} client-PBDT-195133201.csj

{your_password} – The same password that you chose in step 4
{your_pin} – The pin you created when you requested the registration files in step 3
client-PBDT-195133201.csj – Change this to the name of the PBDT CSJ file that you received in your registration files email in step 2

Generate a debug token to allow deployment of debug builds to the Blackberry Playbook tablet

6. Open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-debugtokenrequest" -cskpass {your_password} -keystore sigtool.p12 -storepass {your_password} -deviceId 0x{device_id} name_of_your_debug_token.bar

{your_password} – The same password that you chose in step 4
{device_id} – Your Blackberry Playbooks device ID
name_of_your_debug_token.bar – Note that you should not use any funny characters or spaces in this name, best bet is to name it something like companynamedebugtoken.bar

NOTE: To find your Blackberry Playbooks device id do the following:
* Tap the settings icon in the top right hand corner of the playbooks screen to bring up settings
* Select “’About ‘ item on the left hand side menu
* In the drop down box to the right selected “’Hardware’
* The ‘PIN’ number shown is your device ID

Install the debug token to the Blackberry Playbook tablet

7. if you haven’t already done so then ensure that you have connected your Playbook to your local Wi-Fi network. Go to Settings->Wi-Fi and set it up here.
8. Go to settings->About then select ‘Network’ from the drop down list to the right which displays info about your network. Now note down the IP address of the Playbook (something like 192.168.1.2)
9. Enable “Development Mode” on your Blackberry Playbook as follows:

* Go to Settings->Security->Development Mode
* Slide the development mode slider to “On”
* You will be asked to enter a password (for simplicity use the same password as you use for logging into your Playbook)
* Select “Upload debug token” button

And finally to install the debug token to the Playbook, open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt to install the debug token to the Playbook

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-deploy" -installDebugToken name_of_your_debug_token.bar –device {ip_address} –password {playbook_password}

name_of_your_debug_token.bar is the name of your debug token that you create in step 6
{ip_address} – The IP address that you noted down in step 8
{playbook_password} – This is the security password that you have set for your Blackberry Playbook (The one you type in when you log into your Playbook)

Ok, the hard bit is out of the way, take a breather and go for a coffee, next part is deploying via the Marmalade SDK, which is thankfully a much easier process

Deploying your Marmalade SDK app to the Blackberry Playbook tablet

There are a few things you need to do on the Marmalade side in order to get your build ready for deployment to the Blackberry Playbook:

10. MKB project file modifications

* If you want to appear as the author for your app then you need to add the following to the Playbook deployment section of your MKB:

playbook-author='Your company name'

* So that RIM can identify you as the real author of the app they need to know your author ID. The line in your MKB will look something like this:

playbook-authorid='gBACAgDE-PVmaTowNV2UQzp61q32'

The aiuthor-id is however a little elusive. The easiest way to find it is to rename the “name_of_your_debug_token.bar” file that you generated in step 6 as a zip file “name_of_your_debug_token.zip” for example. Open the zip file and extract the MANIFEST.MF file. open this file in a text editor and fiind the field called “”Package-Author-Id” the value for this field is the authorid you need to supply to the Marmalade build system

* To set the Splash Screen and icon use the following two MKB commands:

splashscreen=PlaybookSplash.png
icon=PlaybookIcon.png

The splash screen and icons will be scaled to the correct sizes, but I recommend choosing a large sized splash screen that matches the 1024 x 600 pixel aspect ratio screen and 86 x 86 pixel icon (rounded corners and transparency are allowed in the icon)

Ok, now you have this in place, compile and run your ARM release build. When the Marmalade deployment tool runs and gets to the final stage of deployment you need to enter the following details:

* Device hostname (or IP address) – Enter the IP address that you noted down in step 8
* Device password – Enter your playbook security password (The one you type in when you log into your Playbook)

If you selected Package and Install in the previous Marmalade deployment step then you should find your apps shiny icon on the Playbooks screen (under games category most likely)

Ok, you can now deploy your build to an actual Blackberry Playbook, but what about preparing your BAR file for submission to Blackberry App World, we shall cover that next

Preparing your app for submission to the Blackberry App World Store

In order to submit your app to Blackberry for App World approval you will need to sign your BAR file:

11. Edit the file located at “\Marmalade\5.1\s3e\deploy\plugins\qnx\MANIFEST.MF” and change the line that reads “Application-Development-Mode: true” to “Application-Development-Mode: false”. Remember to change it back to true when you are deploying development builds
12. Open up a command prompt and change to the folder where you MKB is located (lets say for example ‘e:\Apps\CoolGame’)
13. Copy the file ‘sigtool.p12’ from the ‘Playbook’ folder that you created in step 4 into the folder specified in step 12
14. Run the following commands at the command prompt: (when resigning the same build you only need to perform steps 12 and 14)

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -verbose -cskpass {your_password} -keystore sigtool.p12 -storepass {your_password} build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar RDK
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -keystore sigtool.p12 -storepass {your_password} build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar author

{your_password} – The same password that you chose in step 4
build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar – You need to replace this section with the relative path to your .BAR file for your app

You now have a signed BAR file that you can submit to Blackberry App World for approval! Good luck with your submission and good luck with sales!

A Few Notes

* You can choose a separate CSK password and store password if you like to increase security
* Remember to replace the path to the Blackberry tools with the correct path for your Blackberry SDK install
* Our app only took around 16 hours to get approval but we noticed that the number of new apps appearing around our time of submission were few and far between so it could take longer
* Ensure you have a working internet connection throughout the whole process as the Blackberry tools will need to query various external servers
* If you are having trouble with deploying your debug build then ensure that a) Your Blackberry Playbooks IP address has not changed and b) Your debug token has not expired (they have a very short life span)
* If you would like your app to be classified in a category other than “’games’ you will need to change the application category line “Application-Category: core.games” located in the file “\Marmalade\5.1\s3e\deploy\plugins\qnx\MANIFEST.MF”

Confirming that your app has been signed

To confirm that you app has been signed by both the RIM signing authority and yourself open your BAR file as a zip file and check the META-INF folder. This folder should contain 5 files:

* AUTHOR.EC
* AUTHOR.SF
* MANIFEST.MF
* RDK.EC
* RDK.SF

If any are missing then something went wrong and you need to sign again. Note that if you receive an error saying something along the lines of “already signed” then change your version number, rebuild and re-sign

Android Apps – The Hard Sell? – Comparison of Android App Stores Included

Selling your wares on the Android platform is what some would call “a waste of time” and to be honest I would be very tempted to agree with them. Why would this be the case you may ask? In this article I will attempt to answer that question as well as put forward a comparison of a number of Android app stores, so you know which are worth the effort and which are waste of your time.

In this article I am going to use our latest app “Funky Cam 3D” for Android phones and tablets (http://www.funkycam3d.co.uk) as a frame of reference.

Our company Pocketeers Limited (http://www.pocketeers.co.uk) released its latest Android app “Funky Cam 3D” across a number of Android app stores a few weeks ago. To date we have had a grand total of 14 sales, YES, you did read that right “14” sales. The very same app on iOS has sold 20x that amount in half the time and 10x as many on Samsung Bada in just 2 days

Ok, so we took the rather disappointing sales on the chin and came up with a cunning plan to get the app selling somehow. Our first idea was to drop the price to free for a few days in an attempt to increase the apps popularity with users. Unfortunately the Android Market does not allow developers to change an app from free to paid, which means as soon as a developer changes their app to free they cannot change it back to paid without deleting the app and re-launching it under a new name.

So as an alternative we decided to release a free ad-supported version of Funky Cam 3D. Going on how badly our app was selling we were surprised when many thousands of Android users downloaded our app across various app stores and directly from our web site.

Ok, now the “pain in the ass” bit. Submitting apps to the various app stores is a difficult and time consuming process, a process that will bring you close to tears. Each developer portal has its very own submissions system as well as required art work sizes and formats. Unlike when you submit an app to Apple for certification you find that you spend days on the task of submitting your apps information to the various app stores out there. Why not just submit the app to the Android Market you ask, surely the Android market would offer the greatest exposure? Maybe the following figures will clear this up:

Android Download Statistics for Funky Cam 3D

Our own web site – Over 15,000 downloads (we posted our APK link to various public forums and warez forums)
Appia – 3880 copies
Android Market – 2506 copies
SlideMe – 1198 copies
Mobiles24 – 701 copies
Mobango – 549 copies
Mikandi – 143 copies
AndroidPit – 134 copies
GetJar – 48 copies
Handster – 19 copies
Soc.io mall – 0 copies

As you can see from the above list we have some clear winners and some clear losers. Notable points:

* It would appear that one of the best ways to market free apps is from your own web site coupled with aggressive marketing.
* Appia actually beat the Android Market by a substantial margin, which surprised us. In case you are wondering Appia supply apps to various partners such as Handango, Pocketgear and Mobile2day
* SlideMe figures were a big surprise, we did not expect such figures from what we thought as a minor portal
* Our biggest surprise above all was how badly our app has performed on GetJar, which is supposedly one of the largest app distributors on the planet (we just have no explanation)
* Our greatest downloads came from warez forums. We expected a lot of downloads from this source but were knocked back by just how many we got

So above all else, what did we learn from our little Android app experiment? Well, we learnt that Android users don’t like to pay for apps but will download free apps in droves! A mentality we have coined “frap-mentality”. We also learnt that Ad supported apps do not offer a sufficient return even if downloaded in the 10’s of thousands. Our ad revenues are enough to pay for a cheap meal at the local public house (maybe a subject for a new blog)

If you are considering building a business around developing apps or gaming products for the Android platform then make sure that it is your 2nd choice of platform. Use a cross platform development system such as the Marmalade SDK (http://www.madewithmarmalade.com), this way you can re-target Android quite easily without significant investment in Java or the Android SDK.

You can download Funky Cam 3D from the Android market at:

Funky Cam 3D on the Android Market and
Free version of Funky Cam 3D on the Android Market for those that like shiny new Ads

Update 30th August 2011

Quick download figures update to this post:

Our own web site – Over 17,000 downloads (slowed substantially)
Appia – 13526 copies (massive increase)
Android Market – 4188 copies (pleasant increase)
Mobango – 2623 copies (huge jump)
SlideMe – 1503 copies (up 50%)
Mobiles24 – 942 copies (up a little)
AndroidPit – 214 copies (nearly doubled)
Mikandi – 174 copies (up a little)
GetJar – 154 copies (almost tripled but figures are still terrible)
Handster – 34 copies (good increase but still low figures)
Soc.io mall – 0 copies (Hmm, are these guys alive?)

Update 9th October 2011

Quick download figures update to this post:

Appia – 73665 downloads (massive increase)
Our own web site – 22,000 (slowed considerably)
SlideMe – 12306 downloads (massive increase)
Android Market – 11070 downloads (huge increase)
Mobango – 5042 downloads (good increase)
AndroidFreeware – 3189 downloads (new addition)
1Mobile – 1955 downloads (new addition)
Mobiles24 – 1673 downloads (respectable increase)
AndroidPit – 441 downloads (nearly doubled)
GetJar – 366 downloads (good increase, but I thought that this app store was supposed to be the largest free app store out there?)
Mikandi – 274 downloads (up a little)
Handster – 96 downloads (good increase but still low figures)
Soc.io mall – 1 download (woohoo at last!)

Downloads have nearly doubled in most app Android stores , but some app stores are clearly flying ahead!

Update 16th October 2011

Another quick download figures update to this post:

Appia – 93014 downloads (no stopping Appia)
Our own web site – 22,000 (stopped tracking, its too much effort)
SlideMe – 14260 downloads (slight jump)
Android Market – 12233 downloads (slight jump)
Mobango – 5109 downloads (slight increase)
AndroidFreeware – 3317 downloads (slight increase)
1Mobile – 1955 downloads
Mobiles24 – 1770 downloads (slight increase)
AndroidPit – 473 downloads (slight increase)
GetJar – 400 downloads (up a bit)
Mikandi – 284 downloads (up a little)
Amazon App Store – 128 downloads over 2-3 months (This is the paid version but Amazon have had it free that long it counts as free for this article)
Handster – 103 downloads (tiny increase but still low figures)
Fasmicro – 34 downloads (new addition, around 2 months data)
Appoke – 2 downloads (new addition, live 6 days)
Mobireach – 2 download (new addition, 4 weeks data)
Soc.io mall – 2 downloads (we got another download :))
CNET – 1 download (new addition, 5 weeks of data)

Update 6th November 2011

Another quick download figures update to this post:

Appia –  148390 downloads
SlideMe – 20286 downloads
Android Market – 15276 downloads
Mobango – 5393 downloads
AndroidFreeware – 3616 downloads
1Mobile – Removed as 1Mobile no longer show download stats
Mobiles24 – 1975 downloads
GetJar – 724 downloads (in contrast one of our very old J2ME mobile game DEMOS  has been downloaded 3.759 times in the same period, making GetJar very much still a Java ME app store)
AndroidPit – 549 downloads
Mikandi – 312 downloads
Amazon App Store – 170 downloads
Handster – 126 downloads
Fasmicro – 38 downloads
Mobireach – 17 downloads
Appoke – 14 downloads
Soc.io mall – 8 downloads
CNET – 1 download

Other Android Developer Downloads / Sales Statistics

I will list here any other developers Android sales / downloads statistics that I come across:

Ziggys Android Download Statistics at ZIggy’s Games

If you would like a link to your Android download or even sales statistics posting here then let me know