Coding and deploying for the devices with 10.1 OS

Even if your older 10.0 Z10 version of the app runs “fine” on the newer 10.1 devices (Q10 and upcoming Z10 update) running the 10.1 OS version, you should try to use the latest 10.1 SDK. Why? Starting with the 10.1 SDK, you get access to some new features which will enhance your app’s experience on the Q10 devices significantly. This particular blog post here is a great source of information when you are converting your Z10 app for the upcoming Q10 devices. In terms of the UI elements that you can leverage as a developer, among others, you now have access to certain components like the auto hiding ActionBar, customizable/freeform and sticky TitleBar – these elements will allow you to maximize your screen real estate (for the smaller screen Q10 devices) and provide more room for actual content for the users.

Key shortcuts and listeners are some of the other slick new features; they make common tasks much easier for your users. The Q10 devices are definitely designed for the power users who love the physical keyboard and who value productivity greatly. You want to show them as much useful content as possible (even in the smaller screen) and require as few user input as possible to get to the primary features and content.

What about my current applications for the Z10 devices?

If there are any updates or bug fixes necessary for your currently public Z10 versions of the app (made using 10.0 SDK), you definitely don’t want to keep your users waiting. Until the in-market Z10 devices receive the 10.1 updates, you should continue posting updates and bug fixes as necessary. Going forward, the new 10.1 features that you will be using for Q10 devices (which you definitely should be) and upcoming Z10 updates; if they are mainly on the QML asset files, you can just continue to maintain just one BAR file. All the 10.1 specific QML code; those asset files can be placed in the folder called 720×720. For devices running lower 10.1 OS, that folder will just be ignored and only the QML files in the root folder would be considered. You can check out the github sample apps here to look at the code for projects like these. If you are using any new 10.1 C/C++ API then your application would need the latest 10.1.X.X SDK to compile against to bypass all the compile errors (the corresponding BAR file would also be a different one, since it would need the minimum 10.1 platform to run against).

Project Explorer View

The QML code under the 720×720 folder. It is using some new 10.1 specific features (e.g. customizable TitleBar).
If the same BAR file is run on the 10.0 devices, this code won’t be executed (the folder will be ignored).
Note: This is a modified sample code shown here just for demonstration

The QML file under the root assets folder; this will run by default. Note that there is no 10.1 specific code here

Note that you can install all the different SDK versions through the IDE update options and install the different OS versions. Re-iterating what is mentioned on the release notes:

• If you are developing using a BlackBerry 10 Dev Alpha device, you need to download the 10.0.10.263 target from the update site.
• If you are developing using the BlackBerry Z10 smartphone, you need to download a target from the update site that matches the device version that’s provided by your wireless service provider. You can verify the device version by opening the Settings app, tapping About, selecting OS in the Category drop-down list, and checking the version that’s listed in the OS Version field.
• For more information about developing apps that work on different versions of the BlackBerry 10 Native SDK, see Appropriate version of the BlackBerry Native SDK in the BlackBerry Support Community Forums.

How do I specify restrictions to BlackBerry World and BAR files?

When you are submitting the signed BAR files through your vendor portal account, you can choose the minimum OS version and the devices accordingly. These settings control whether or not your app will show up on the users’ BlackBerry World app (depending on the devices and the OS version they are currently running on).

Note that there is also a specific value that can be set through the bar-descriptor.xml file, which dictates the minimum required platform OS version required to install and run the app. This in turn gets reflected on the final signed BAR produced (MANIFEST.MF file). Do not modify this default value set unless you are absolutely certain which device OS versions you want to prevent the app from being installed (even if they are discovered through the BlackBerry World app). This value is checked by the OS itself when the app is installed and run using the BlackBerry World app. However, this is not something that the BlackBerry World looks at (currently) to filter what apps the user can see to download. This means, if you are playing around with this value, there could be instances where the user can see or buy the app through the BlackBerry World app but not be able to install it! The vendor portal filtering only gives you granularity between 10.0.0, 10.0.10 and 10.1.0 for now but if you are modifying the bar-descriptor.xml value for this, you can end up being really specific (10.0.9.X, 10.0.10.X, 10.1.X.X) which could prevent your users from installing the app (even if they are being able to see it or buy it).

The bar-descriptor.xml editor from the QNX Momentics IDE

Viewing the resulting signed BAR file through the IDE (MANIFST.MF file)

Viewing the resulting signed BAR file through the IDE (MANIFST.MF file)

Managing code base

Since there are newer API/libraries with 10.1 SDK, you might already be thinking about how to manage your code base better. Well, there are a few different options to choose from:

1. If you are already using a version control system like Github, just use the branching and merging technique for your code base
   • Create a new branch from your latest 10.0.X.X code version. Add all the new 10.1 features here and continue to use this one for devices running 10.1 (Q10 devices for now and soon to be Z10 as well)
2. If your 10.1 changes (e.g. using some of the newer UI elements and features) are mainly on the QML assets, you can make use of the static asset selector which is new with 10.1. Basically, your IDE will be pointing to the same project (code base) but based on which device you are targetting your app, it will select the respective .qml files
   • As mentioned before, the Z10 devices running lower than 10.1 OS, will just ignore the folders such as the 720×720
3. If you are using 10.1 specific API in your C++ code (only), you can use the NDK versioning macros to detect the OS versions. This forum post here talks about this in details

To Sum Up

• For devices running 10.1 OS, definitely use 10.1 SDK to compile and deploy your app; make use of all the useful features which will make the Q10 experience of your app significantly better
  • As soon as 10.1 OS is picked up by the Z10 devices, these app releases will be shown through BlackBerry World as well (provided you set the vendor portal filtering accordingly)
  • There is more than one way to manage your code base; you have to decide which one is best for you
• For posting updates and bug fixes to the 10.0 Z10 versions of your app, continue to use the respective 10.0 SDK to compile and deploy the app
• Sanity check: Don’t forget to test and try out the application on the OS versions that your users are expected to run the app

We hope at least some of this was helpful to you. If we have missed any particular cases, do bring them to our attention and we will try to advise accordingly. Hope to see all of your apps for the Q10 devices soon!

Hopefully you aren’t getting tired of me yet, and I’m sure you are not tired of the updates to the BlackBerry® WebWorks™ SDK. We’ve just posted a new release, and it squarely falls in the high-value realm. While incremental, it empowers a significant feature of the BlackBerry WebWorks platform: custom API extensions. That’s right, like previous BlackBerry WebWorks platforms, you can now write your own extensions to enable native capabilities not yet exposed by the pre-packaged BlackBerry WebWorks APIs!

First, let’s quickly mention the other major item in this release: Now, when you build your application, you can pass a configuration file to bbwp.exe – the main command line tool for BlackBerry WebWorks – which will pass parameters on to the other downstream command line tools that bbwp.exe leverages. bbwp.exe is your main command line tool to create your applications for BlackBerry WebWorks: it will give you your .BAR file and even sign it for you. However, under the covers, it uses a couple of other command line tools that are part of the BlackBerry tool chain to perform these actions such as creating the .BAR and signing it. These other tools sometimes have parameters that are not exposed by bbwp.exe. With this release, we have provided a parameter (-p or –param) on bbwp.exe to provide a file on the bbwp.exe command line that you can use to pass on to the downstream tools any additional parameters you choose. It is a simple json structure that you can mark up. The main use case we hear quite often is providing the signing tool with proxy settings. Check out the params-example.json file in the root of your BlackBerry® 10 WebWorks SDK installation for an example. It contains the framework for providing parameters to the other two tools, the native packager that creates the .BAR, and the signing tool which signs the .BAR.

OK, now back to custom extensions. As a quick recap, BlackBerry WebWorks APIs are conceptually comprised of two different things: an API or service in the native platform, and a JavaScript® front-end to this native service. All of the APIs that are part of the official BlackBerry WebWorks SDK take advantage of this architecture and a system called jNext. jNext is what binds the JavaScript layer to the native layer. You can now build your own API extensions in exactly the same way we do.

To get started, you will first need to download our BlackBerry 10 Native SDK and configure it. This will give you access to all that the native environment offers. Go do that now and come back here for the next step.

All right, you’re back. Next step is to visit our GitHub Community API repo and download the sample BlackBerry 10 Native SDK project we have provided. This sample project is a working example of an extension that monitors memory usage on the device. Everything you need to create your own extension is modeled here. A full walk-through of the project and its components can be found in the README associated with the project in the GitHub repository, so check that out next, and get working on your extension.

Once you are done, I highly recommend that you check out our Community API repository, and seriously consider contributing your extension to the repository so that others can take advantage of your awesome work. To contribute the extension you will need to apply the ASL 2.0 license, and complete a few other administrative things, but then the whole BlackBerry WebWorks community can benefit.

One thing to bear in mind with your extension: we really didn’t want to hold back on releasing this feature to our community, but we do know that one thing will change in our next BlackBerry WebWorks SDK release. When you completed your extension, you would have had to create/modify a file called manifest.json. This file provided metadata regarding your extension. Moving forward, we will very likely model the format of this file after the CommonJS package.json file format (used by npm modules). This should not constitute very much refactoring, as the current file format is very concise, and the community alignment is valuable in itself.

OK, that’s it for this release. As always the team is working on some exciting stuff for the next release. I can’t wait for the next release! Until then, head over to our download page and our GitHub repo to start working on your custom extensions!