So we’ve updated the socialinvocation sample to include examples of how to invoke Foursquare with all of the currently supported invocation parameters.

As you can see, Foursquare allows BlackBerry 10 developers to leverage their app in a number of different ways, both through Cards and the Invocation Framework.

Big thanks to Kyle from Foursquare who has also documented these features in his sample app:  https://github.com/foursquare/foursquare-bb10-sdk

If you want to learn more about Social Invocation and why you should be including it in your app, come to one of our sessions next week at BlackBerry Live!  We’ll be talking about the benefits of integrating with Foursquare and the rest of the Social apps in two sessions:

JAM37 - Building context-aware applications by leveraging the power of Foursquare APIs, Thursday, May 16

JAM52 - Get Social: Connecting your app to Facebook, Twitter, Foursquare, and more! Wednesday, May 15

Kyle from Foursquare will be there, and we will show a real world example of how Untappd found success by integrating with Foursquare.  Sample apps, best practices, and code snippets will also be presented that will show developers how to quickly get started in both the BlackBerry WebWorks SDK and the BlackBerry Native SDK.

This article will aim to explain how to build a native app from the command line, using the tools bundled in the BlackBerry 10 Native SDK and your favourite text editor.

Set up your environment

The Native SDK includes a script called bbndk-env.sh (or .bat on Windows) in the root folder that initialises the environment variables that the other tools depend on. I will refer to the install location of the Native SDK as $NDK_DIR.

Mac: source $NDK_DIR/bbndk-env.sh
Win: $NDK_DIR/bbndk-env.bat

So what does this script set?

The most important environment variables are:

QNX_TARGET: This directory contains all the configuration files and libraries for the BlackBerry 10 device, the target that we want our app to run on.  You can see all the libraries which can be linked against in $QNX_TARGET/armle-v7/lib and $QNX_TARGET/armle-v7/usr/lib.

QNX_HOST: This directory contains the tools and configuration files for our host system, ie Windows, Mac or Linux. It includes a compiler, linker and assembler for cross compiling to various architectures, as well as command line tools for packaging, signing and deploying your application.

Building for the ARM architecture

You may have noticed the use of armle-v7 in the above directory structure. This refers to the processor architecture on BlackBerry 10: ARM Little Endian Version 7. To build binaries that run on BlackBerry 10 you need to compile for this architecture.

Start by creating a folder to hold our app’s files, call it GoodbyeIDE. From now on I will refer to this as $PROJECT_DIR. Inside this folder create a file called main.c with the following content:

#include <stdio.h>
int main()
{
  fprintf(stdout, "Goodbye IDE!\n");
  return 0;
}

Now lets compile it. Change to $PROJECT_DIR and execute:

qcc -Vgcc_ntoarmv7le main.c -o main

Lets explain this command in a bit more detail. qcc stands for QNX C Compiler. BlackBerry 10 is built on top of QNX and uses many of its build tools.

qcc is essentially a wrapper for gcc  (GNU Compiler Collection). The -V switch tells qcc which version of gcc to use, in this case its the ntoarmv7le version which stands for QNX Neutrino ARM Version 7 Little Endian (a bit of a mouthful).

To build for the BlackBerry 10 simulator you need to use the gcc version for the x86 architecture.

qcc -Vgcc_ntox86 main.c -o main

To view a full list of the available gcc versions run:

qcc -V

The main.c -o main part of the command just specifies the input C filename and output binary filename.

OK, so now we should have a binary (called main) that will run on a BlackBerry 10 device. This binary won’t run on your host operating system since it’s not compiled for the same architecture. If you have a working gcc you can compile it by doing:

gcc main.c -o main2
./main2

When you execute main2 you should see “Goodbye IDE”.

Create the BAR descriptor XML

BlackBerry 10 apps are packaged as BAR (BlackBerry Application aRchive) files. To create a BAR file we need a descriptor file called bar-descriptor.xml. This file includes information about the app such as name, version, required permissions and a list of assets.

Create the bar-descriptor.xml file with the following content:

<qnx>
  <id>com.example.GoodbyeIDE</id>
  <versionNumber>1</versionNumber>
  <name>Goodbye IDE</name>
  <asset path="main" entry="true">main</asset>
</qnx>

From our point of view the most important line in bar-descriptor.xml is this one:

<asset path="main" entry="true">main</asset>

This specifies that the BAR contains a file called main which is the entry point for the app.

A full list of BAR application descriptor parameters is available here.

Packaging and deploying your app

Now that we have a binary and an application descriptor we are ready to create a BAR file.

A BAR file is essentially a zip file which contains all your app’s assets and the meta information from bar-descriptor.xml. In fact, if you rename a .bar file to .zip you will be able to extract it to see all the files in that app.

To create a BAR file run the following command:

blackberry-nativepackager -package GoodbyeIDE.bar bar-descriptor.xml -devMode -debugToken ~/Library/Research\ In\ Motion/debugtoken1.bar

Note that the -devMode and -debugToken flags are only required if you are deploying to a physical device. This is a handy feature that allows you to deploy your app without signing it, as long as your debug token is installed on the device.

To do this you’ll need to register with RIM to sign applications and create a debug token.

So now you have a BAR file called GoodbyeIDE.bar you can deploy it to the device using the following command:

blackberry-deploy -installApp 169.254.0.1 -password pass GoodbyeIDE.bar

169.254.0.1 is the IP of your target and pass is the device password.

If you take a look at your application icons, you should see a new one called Goodbye IDE (as specified in the <name> tag in bar-descriptor.xml).

If you tap on the icon your app should run! But…nothing happened, right?

Viewing log files over SSH

Actually the app did run, it’s just that all it did was print “Goodbye IDE!” to the stdout. The stdout on BlackBerry 10 is directed into a log file. We can view this log file by SSHing onto the device. Here’s how:

First we have to tell the device that we want to create a secure connection to it:

blackberry-connect 169.254.0.1 -password pass

Now open an SSH client (such as putty) and run:

ssh devuser@169.254.0.1

You should now be connected via SSH. Feel free to poke around! Apps are installed in /accounts/1000/appdata. Each app is given its own sandbox folder with a unique name based on its id (which we specified in bar-descriptor.xml).

Example sandbox folder name: com.example.GoodbyeIDE.testDev__GoodbyeIDEcf9b848

The log file can be found in the logs directory under the sandbox folder name. To view the file just run:

cat log

The log file is re-created each time the app is run. To test that the app is working delete the log file, tap on the app icon and run the above command again.

Summary

That’s it for now. The next article will focus on making your life easier by using Makefiles, the Qt build system and creating a more logical project folder structure.

With the upcoming release of BlackBerry Q10, there’s never been a better time to bring over your BlackBerry Z10 game and start monetizing on the new form factor. In this post, I will be talking about various porting considerations and best practices to help you get started and ensure that your game runs the best on Q10.

Let’s start off with the hardware differences:

The BlackBerry Q10 uses the same chipset and GPU as BlackBerry Z10 variant B with Qualcomm Snapdragon MSM8960 and Adreno 225. The main differences that you need to consider are aspect ratio, screen size, orientation and physical keyboard.

Aspect Ratio

If you have designed your game around the 16:9 or 15:9 aspect ratio, you will need to evaluate how to layout your game content to adapt to the 1:1 aspect ratio. There are various approaches you can take to accomplish this. You might be tempted to take the easy approach of simply scaling your game screen to 1:1 aspect ratio by using letter boxing. This approach is not recommend as it could negatively impact user experience of your game.  Since The BlackBerry Q10 has a smaller screen compared to the BlackBerry Z10, you will significantly reduce the game interaction area and waste precious screen space that could otherwise be utilized for game content such as HUD or controls. For a landscape game, one approach you could take to solve this is to use a comprise aspect ratio such as 16:11.  For the BlackBerry Z10, display more content on the sides and for the BlackBerry Q10 display more content at the top and bottom.

Similarly for a portrait game (9:15 or 9:16), you can display more content at top and bottom on the BlackBerry Z10 and more content at the sides on the BlackBerry Q10. In the below example, Bejeweled 2 displays the time progress bar at the bottom on the BlackBerry Z10 and on the side on the BlackBerry Q10.

If you are using any aspect ratio specific static assets such as backgrounds, images and splash screen, they will need to be scaled accordingly. For the standard splash screen, the BlackBerry Native SDK allows you to manage multiple device specific splash screens in the same bar-descriptor. For the BlackBerry Q10 you can add a 720×720 splash screen by editing the bar-descriptor using the IDE or a text editor. Here’s an example:

<splashScreens>
        <image>splash_1280_768.png</image>
        <image>splash_720_720.png</image>
</splashScreens>
      <asset path="assets">assets</asset>
      <asset path="icon.png">icon.png</asset>
      <asset path="/Users/pratiksapra/assets/splash_1280_768.png">splash_1280_768.png</asset>
      <asset path="/Users/pratiksapra/assets/splash_720_720.png">splash_720_720.png</asset>

Once you do this, correct splash screen will be automatically chosen depending on the device your game is launched on.

Next, if your game uses overlay controls such as virtual joysticks, UI elements and menus, you will need to reposition them as needed. The best approach is to lay them out relative to screen width and height thus making them aspect ratio independent. Below is an example of a flexible UI layout used in Bard’s Tale that works on both aspect ratios.

Screen Size

The BlackBerry Q10 features a 3.1” screen surrounded by a gesture sensitive bezel. If your game uses on-screen controls, it’s important to place them away from the bottom edge of the screen to prevent accidental swipes. An accidental swipe-up gesture during game play will thumbnail your game and cause unnecessary interruption for the user.

Optimizing your game controls is also really important. For example, If your game uses dual virtual joystick control scheme, I would recommend reducing this to just one on-screen joystick.  Due to smaller screen size, the user might end up covering most of the screen when controlling both joysticks using two fingers. We will talk about a solution to this in the later part of this post.

Orientation

The BlackBerry Z10 supports portrait as the default orientation. If you are setting the orientation in the bar-descriptor for your game, you might be wondering whether this would work on the BlackBerry Q10 without the overhead of creating a separate binary with a different bar-descriptor. To make your life easy, we have made sure that both portrait and landscape orientation settings map to portrait orientation on the BlackBerry Q10. The below example shows how your game would be oriented on the BlackBerry Z10 and the BlackBerry Q10 based on the bar-descriptor orientation setting.

Input

The BlackBerry Q10 features a physical keyboard so your game needs to be aware of this. If your game contains any buttons to activate the virtual keyboard, you should make sure they are removed or disabled when the game is running on the BlackBerry Q10. Unlike the virtual keyboard, the physical keyboard is always there and can be utilized as an input mechanism.    You can combine keyboard input with touch screen to offer an intuitive and robust input scheme for your game. For example if you want to optimize the dual virtual joystick input mechanism for the BlackBerry Q10, you can substitute one of the joysticks with keyboard input. Or if your game only requires gamepad style input you can use the keyboard as a gamepad.

Integrating keyboard input in your game is super easy. To accomplish this, in your main event loop simply handle the SCREEN_EVENT_KEYBOARD event and check for the keydown value. Here’s a code snippet on how to do this:

if (screen_get_domain() == domain) {

        screen_event_t screen_event = screen_event_get_event(event);

        int screen_val;
        screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_TYPE, &screen_val);

        switch (screen_val) {
        case SCREEN_EVENT_MTOUCH_TOUCH:
//handle touch events

        case SCREEN_EVENT_KEYBOARD:
            screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_FLAGS, &screen_val);

            if (screen_val & KEY_DOWN) {
                screen_get_event_property_iv(screen_event, SCREEN_PROPERTY_KEY_SYM,&screen_val);

                fprintf(stderr, "The '%c' key was pressed\n", (char)screen_val);

                switch (screen_val) {
                case KEYCODE_W:
                    // Handle Up
                    break;
                case KEYCODE_A:
                    // Handle Left
                    break;
                case KEYCODE_Z:
                    // Handle Down
                    break;
                case KEYCODE_D:
                    // Handle Right 
                    break;
                case KEYCODE_L:
                    //Button A
                    break;
                case KEYCODE_P:
                    //Button B
                    break;
                case KEYCODE_K: 
                    //Button X
                    break;
                case KEYCODE_O:
                    // Button Y
                    break;
                default:
                    break;
                }
            }
            break;
        }

Tools & Deployment

To get started, you will need the latest BlackBerry Native SDK 10.1, which includes BlackBerry Q10 support. If you are running an older version please upgrade by visiting http://developer.blackberry.com/native.

To deploy your game on BlackBerry World, follow the regular process for creating a new release in the Vendor Portal. In the supported devices screen, make sure you select BlackBerry Q10.

Known Issues

There are two known issues with earlier versions of 10.1 device software that you need to be aware of.

• Audio – In-game audio playback results in complete loss of device audio and a reboot is required to restore audio.
• Orientation – If the orientation is set to landscape in the bar-descriptor, the app splash screen and system dialogs such as volume are incorrectly oriented.

Both of these issues have been fixed in the latest 10.1 device software posted at the below link so if you are running an older build please upgrade.

https://developer.blackberry.com/blackberry10devalpha/devalpha_update.html

I hope you found the information included in this post useful.  If you have any questions or feedback please leave a comment below or reach out to me directly on Twitter @pratiksapra.

So, we thought we’d try a little bit of BlackBerry 10 Bluetooth Low Energy (LE) magic to help us. This  follows on nicely from my previous Blog post on the Internet of Things and the model is more widely applicable than just finding lost keys. In fact, if you haven’t already done so, this is probably a good time to have a read of that blog post and article since it covers the basic concepts needed in this blog post.

Go on … I’ll wait and have a cup of tea.

Ah, ok, you’re back … right, let’s continue.

The first thing we did was to do a little bit of research to see if the Bluetooth SIG had set any standards in this area; no point in re-inventing the wheel and the existence of a standard would mean that a vendor may have already implemented the technology in a product.

Whenever you have a requirement that may be solvable using Bluetooth LE the first place to look is here: http://developer.bluetooth.org/gatt/Pages/default.aspx.

Browsing through the GATT Profiles we came upon this one: Find Me … this sounded promising!

To quote the Abstract for the Find Me profile, “The Find Me profile defines the behavior when a button is pressed on one device to cause an alerting signal on a peer device”. An image formed in our minds immediately!

A closer look shows that this profile implemented a GATT Service called Immediate Alert which used a GATT Characteristic called Alert Level … this looked a perfect match.

Here’s the description of the Alert Level Characteristic.

Alert Level Characteristic

It’s an 8-bit unsigned integer that can take on three values signifying:

• No Alert
• Mild Alert
• High Alert

The interpretation of these Alert Levels is the responsibility of the device that implements this characteristic.

Having found the Bluetooth LE Profile that matched our requirements the next step was to find a simple device that implemented it.

We found this one (see Figure 2) from Texas Instruments[1].  As well as supporting the Find Me profile it also allows re-programming with other Bluetooth services.

Texas Instruments CC2540/41 Mini Development Kit

Out of interest, I used one of the tools ( BTool ) that came with the key-fob to examine the GATT services that this device supported. Here’s a screen shot:

GATT Services present on the key-fob

So, you can see the highlighted red box clearly shows the Immediate Alert Service which has UUID 0×1802 (integers are represented in little-endian order so 0×1802 is represented as 02:18) and the Alert Level Characteristic which has UUID 0x2A06. Notice that the value field of the Alert Level characteristic has been assigned a handle of 0×0028 – handles are discovered by and used by applications to access fields in the GATT Service list and they’ve been covered in a previous blog post and article.

The application that we developed based on this is actually very similar in structure to the Heart Rate Monitor application that was described in a previous blog and article. The basic logic is the same:

1. Pair the Bluetooth LE device with the BlackBerry 10 handset before using the application.
2. Launch the application which:
   1. Discovers devices that support the Immediate Alert Service
   2. Connects to a discovered device selected by the user
   3. Offers the user the choice of Alert Levels ( Off, Mild and High) to be sent to the device

Here are some screenshots showing what the application looks like:

Screens from the application

You can see that the buttons at the top of the screen become enabled only once the application has connected to the Immediate Alert Service on the key-fob. If you select the “High” option this device will emit a loud buzzing sound and flash a green LED.

Application Sending an Alert to key-fob

This is the application in action. If you use your imagination you can hear the buzzing and I can find my keys!

The key part of the application is where the Alert Level is sent to the device. Here’s the section of code that does this:

void FindMeService::sendAlertRequest() {

       uint8_t level[] = {0};

      switch (_alertLevel) {
            case FindMeService::Off:
                  level[0] = 0;
                  break;
            case FindMeService::Mild:
                  level[0] = 1;
                  break;
            case FindMeService::High:
                  level[0] = 2;
                  break;
            default:
                  level[0] = 0;
                  break;
      }

      errno = 0;

      if (bt_gatt_write_value_noresp(
                    _serviceInstance,
                    _alertLevelValueHandle, 0, 
                    level,
                    sizeof(level)
          ) != EOK) {

             qDebug() << "errno=(" << errno << ") :" << strerror(errno);
      }
}

You can see that we’ve already connected to the Immediate Alert Service and have a reference to this in the variable _serviceInstance; we also have a handle to the Alert Level characteristic value _alertLevelValueHandle. The API used is bt_gatt_write_value_noresp()which means that the Alert Level (level) is written to the device and no acknowledgement is expected in return.

Wait, I hear you say! How did you know that you had to use a Write without Response to write the Alert Level value to the device? Well, it’s part of the definition of the Immediate Alert Service. Here (Figure 6) is the definition of the Alert Level characteristic from the definition of the Immediate Alert Service. It says that this characteristic can be accessed only though the Write without Response request.

Immediate Alert Service Alert Level Characteristic Properties

And, just to confirm that the device understands and enforces this as well, Figure 7 shows this value in the GATT‘s entry for the Alert Level characteristic – the value 0×04 in the green box is the encoding of this property.

Characteristic Properties of the Alert Level

We made a video which has Martin (@mdwrim) showing the application in action and explaining the code. Here it is:

http://youtu.be/UXEt5tfUEdc

If you want to know more then check out the following resources:

• The complete source code for this application on Git Hub;
  • https://github.com/blackberry/Cascades-Community-Samples
• A Bluetooth Primer level Blog Post is available here to get you started:
  • http://devblog.blackberry.com/2013/04/bluetooth-low-energy-and-the-internet-of-things/

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.

“Bluetooth Low Energy”, I hear you say. ”I know all about Bluetooth since that’s been around for many years. It’s what I use to connect my headset to my BlackBerry device and play music though my sound system. What’s this ‘Low Energy’ thing?”

Well, the Bluetooth specification went through a number of changes a couple of years ago when Bluetooth 4.0 was released. Bluetooth Low Energy (LE) is an addition to the classic specification that allows ultra low power devices to participate in Bluetooth Networks.

What does “Ultra low power” mean? Well, Bluetooth LE is designed to support devices that would typically be powered by battery cells like the one in this picture.

That means that such devices can have incredibly small footprints yet can be full participants in a Bluetooth network alongside larger devices like tablets or smart phones such as BlackBerry 10 smartphones.

It also means that this awesome technology is an enabler for the “Internet of things” where such devices can participate in an Internet populated with all sorts and sizes of devices ranging from large servers to intelligent thermometers; from tablets to intelligent sensors in your running shoes; from mobile phones to intelligent light switches in your home.

Imagine being able to use your BlackBerry 10 smartphone to tailor your environment to your preferences as you move around. It’s already capable of knowing where you are and Bluetooth LE gives it the capability of communicating with smart devices in your home or car. Imagine returning home and having your BlackBerry 10 smartphone communicate with your lighting to set it appropriately; your home entertainment system to play your favourite playlist; and your house’s environmental controls to set just the right temperature!

The diversity of potential applications is quite staggering. Sports, wearable devices, home automation, automotive and healthcare, are just a few of the sectors recognising the potential of Bluetooth LE.

And … BlackBerry 10 is a perfect fit here! So, we got to thinking how we could demonstrate how easy it is to integrate Bluetooth LE technology into your BlackBerry 10 application!

In order to provide some focus for this activity we acquired some Bluetooth LE technology and tools including a Wahoo Blue HR device to see what we could do with it. There are a number of similar devices on the market but this seemed like a good starting point. It’s a small, lightweight electronic device, encased in plastic. It has an adjustable strap to allow you to strap it around your chest and the strap has two conductive pads which need to be in contact with the skin.

The nice thing about Bluetooth LE is that there are standards for devices like this that support what’s called the Heart Rate Profile and we managed to develop a nice, even though I say it myself, self contained BlackBerry 10 application that interacted with the heart rate monitor and displayed it’s data.

Take a look at the images below! The image on the left shows a typical trace for a healthy person like Martin who went on a long, exhausting bike ride to gather this data.

The middle one is probably from a small, hyperactive animal like this hamster; whilst the one on the right probably comes from a hibernating hedgehog I came across in my garden.

Rest assured that no small timid animals were involved in our testing other than in our imaginations!

If you want to know more then check out the following resources:

• A much more detailed article describing the theory and practice behind this application
• The complete source code for this application on Git Hub
• A video on YouTube showing an overview of the theory and practice behind this application

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.

“A beautiful use of the BlackBerry 10 technology.”

“An absolutely amazing app. Well done.

Many of these reviews refer to USA TODAY as a Native app – in fact, some encourage Native developers to produce apps of this quality – especially impressive as it is a 100% HTML5 WebWorks app.

“Great Native App. Very addictive as you can easily navigate through the menu”

“Watch and learn, that’s how you make a native app”

“Must have. Go native or go home!”

USA TODAY is a perfect example of what can be achieved using HTML5 and the powerful BlackBerry 10 WebWorks Platform to produce an app that proudly carries the Built for BlackBerry ribbon.

Performance

Performance was critical to USA TODAY – news, sports, weather, pictures and video sections are combined into a responsive, intuitive viewing experience. Each section contains subsections, while each subsection contains lists and grids of articles. With this much content, view management becomes quite difficult. Having worked closely with Backbone.js (http://backbonejs.org) for a few years, I did not hesitate to recommend it to be the ‘backbone’ of the USA TODAY application.

Backbone.js is a MVC (Model-View-Controller) framework that provides the tools and discipline to write de-coupled, re-usable code while not imposing any non-standard syntax. It is also highly customizable, which is ideal for large projects.

The USA TODAY application uses Backbone.js to its full potential. Articles, gallery, weather, videos, and other data are stored as Data Models and Collections, which are passed to views that combine the data with HTML templates to display it on the screen.

A View is a JavaScript object that contains a set of properties and methods responsible for displaying a region of the application UI. The View also maintains its own DOM structure, which is typically compiled with data to render and display on the screen. HTML templates are code snippets that are re-used across an application. These templates may vary from static pieces of UI to complex dynamic views that contain logic such as loops.

These views are also responsible for listening for changes in the data of the collections and updating regions of UI when a change occurs. Picture the weather section for example: if the weather data on the server changes, we need to update the UI. In order for the UI to reflect the change in the weather and change the graphic from cloudy to sunny, the data model can explicitly tell the view to update, but by doing so, the view becomes tightly coupled with the data model. If we were to add a weather widget to the main screen of the application – we are also required to add a call its update methods from within the data model and so on.

Backbone and other MVC frameworks encourage the use of Publish/Subscribe programming pattern, where views subscribe to changes on the data model. When the data changes on the server, subscribed views receive a change notification, which typically triggers an update of UI. The data model does not need to be aware of what views are subscribed, and therefore remains flexible and de-coupled. This is very similar to how we bind to click events on buttons – imagine having to change the button’s logic to call functions, versus listening for click events.

This pattern also allows for smaller UI region updates. For example, we can bind a function to only update the current weather UI region, if the weather for the week hasn’t changed. Smaller UI updates result in smaller re-render regions, which drastically improve performance, especially when targeting mobile.

The USA TODAY application uses this pattern throughout the application, which makes UI updates efficient and seamless.

Code organization

As the complexity of any application increases, organizing code into modules becomes a necessity. Unfortunately, JavaScript does not natively satisfy all use cases for ‘modules’ yet, so USA TODAY relies on Require.js (http://requirejs.org) to separate code into neatly organized modules that are confined to performing a single task. Require.js supports Asynchronous Module Definition (AMD), that allows modules to be loaded as needed at run-time, rather than making them available as the application initializes using tags. Require also adds the ability to define dependencies, similar to more traditional languages such as C++ and Java. This ensures required scripts or templates are available to the module when it is initialized. This also means fewer name conflicts, as libraries and functions are defined in the scope of the module rather than globally, as with the tag.

The source code for USA TODAY is inside an intuitive folder structure. Views, collections, models and templates are separate. Logic, structure and styles are separated into JavaScript, HTML and CSS respectively, which is a great practice for all HTML5 developers. This allows for easy maintenance and debugging as well as adding of new features, while maintaining stability. Modules can be swapped in and out, as they are designed to be de-coupled from one another, and communicate with each other using a router and URL hashchanges.

UI/UX decisions

Aside from great performance, USA TODAY offers stunning native looking graphics and transitions that make it shine as a Built for BlackBerry App.

The menu, action bar and all other UI elements were made from scratch to closely mimic their native counterparts. They’ve closely followed our UI guidelines, including colors, graphics, sizes that make this application practically indistinguishable from a native BlackBerry 10 application.

(http://developer.blackberry.com/devzone/design/bb10/application_structure.html).

When viewing an article, frequently used actions such as font size and share are located on the action bar, which is very intuitive to both existing BlackBerry 10 users as well as those new to the platform.

Within the article, USA TODAY allows navigating back and forth using swipe gestures. This allows the reader to navigate through a list of articles without ever leaving the article view – a fantastic UX decision that keeps the user immersed in the experience, which is one of the core promises of the BlackBerry 10 platform.

Using the font action, readers can quickly modify the font-size, which is a key feature in any news reader app.

The main menu reveals itself as the content view slides out in a smooth transition, thanks to hardware accelerated CSS3 animations. There is lots of attention to detail here – transitions are timed in way that they don’t interfere with each other, such as the gentle fading out of the content view to focus on the menu, which is done right after the menu is fully revealed, as to not interfere with the sliding animation resulting in a smooth transition.

The main menu is a great example of how to provide intuitive, easy to use navigation for an application that includes a ton of sections and sub-sections. It is also an excellent example of how developers can extend our UI guidelines to enhance the User Experience further. Unlike other BlackBerry 10 Applications, the menu contains sections as well as sub-sections, which adds a great personal touch to the user interface and makes an excellent use of space from a User Experience perspective.

Within ‘Day in Pictures’, clicking on a photograph reveals slideshow mode. Using WebWorks API, device orientation is rotated to landscape and photos are displayed and scrolled in widescreen HD. Tapping on the photo will reveal the header, description and action bar, which fades away in a few seconds – another example of attention to detail. Navigating between photos is done by swiping gestures very much like in the native Pictures app for BlackBerry 10.

(API here: https://developer.blackberry.com/html5/apis/blackberry.app.html#.rotate)

Service Integration

Each article displays a share icon on the action bar, which integrates with the BlackBerry 10 Share framework to display all available media where the article may be shared. The USA TODAY application makes use of the invoke WebWorks API to query the device and return a list of all applications that can be used to share content.

(API here: <a href=”https://developer.blackberry.com/html5/apis/blackberry.invoke.html#.query” target=”_new”>https://developer.blackberry.com/html5/apis/blackberry.invoke.html#.query)

Conclusion

When starting a new HTML5 project, developers have a plethora of frameworks to choose from. Some are used for data and view management alone, while others provide all-in-one solutions, both platform-specific and platform-agnostic. By leaning towards a custom solution with the help of Backbone.js and Require.js, developers at Clearbridge Mobile Inc. remained completely in control over the performance and user experience from start to finish, resulting in a very responsive and attractive application. They’ve followed our UI guidelines, integrated platform services and added a personal touch to the user interface. As a result, USA TODAY is a perfect example of how to build a stunning HTML5 application that is truly Built for BlackBerry.

With the upcoming (and much anticipated) release of the BlackBerry Q10, Android developers can now target the first qwerty-keyboard device to be released on the BlackBerry 10 mobile computing platform. The even better news for developers is that they can also port their existing BlackBerry 10 Android apps running on the BlackBerry Z10 and BlackBerry PlayBook tablet to also include support for the BlackBerry Q10 within the same release build.

While the BlackBerry Runtime for Android Apps has a built-in screen manager which will scale the application to the screen size of the device, it’s always best to build your app specific to the device you are targeting to ensure it looks presentable to end-users.

BlackBerry Z10

For developers, the key difference between the BlackBerry PlayBook, BlackBerry Z10 and BlackBerry Q10 would be in regard to screen sizes. The all-touch BlackBerry Z10 features a resolution of 1280 x 768 (15:9) on a 4.2-inch, 356 PPI screen. Android resources are pulled in from the res/drawable-xhdpi project folder.

BlackBerry Z10 screenshot: 1280×768 background image from res/drawable-xhdpi/device.png

BlackBerry Q10

The BlackBerry Q10 boasts a 330 PPI screen but with a resolution of 720 x 720 on a 3.1” screen (1:1 aspect ratio). When targeting the BlackBerry Q10, Android developers can leverage the res/drawable-small-square project folder.

BlackBerry Q10 screenshot: 720×720 background image from res/drawable-small-square/device.png

BlackBerry PlayBook

In addition to the BlackBerry Z10 and BlackBerry Q10 models above, the BlackBerry PlayBook also supports Android apps. With a 7” screen resolution of 1024 x 600, this qualifies the BlackBerry PlayBook as an mdpi device pulling in resources from the res/drawable-mdpi project folder.

BlackBerry PlayBook screenshot: 1024 x 600 background image from res/drawable-mdpi/device.png

ADT Project Structure

Both the BlackBerry Z10 and BlackBerry Q10 support icons with a size of 114 x 114 pixels (BlackBerry PlayBook: 86 x 86 pixels) which should be placed within their respective res/drawable project folders as well. Within the same Android project you can target both of the BlackBerry 10 form factors within the same release build by following these standard Android best practices.

Single Android project structure for BlackBerry Z10, BlackBerry Q10 & BlackBerry PlayBook

You can repackage your Android APK to the BlackBerry BAR file format using the new v1.5.2 SDK, and test/debug using device simulators for the BlackBerry Z10 (BlackBerry 10 Dev Alpha B), BlackBerry Q10 (BlackBerry Dev Alpha C) and BlackBerry PlayBook  tablet available within our Android tooling page. Other pages which you should find useful would be our documentation page for the BlackBerry Plug-in for ADT and the Android API Support page.

BlackBerry World Submission

After testing your Android application and repackaging it into the BAR file format, you can submit your app to the BlackBerry World storefront via the following steps:

1. Log into the vendor portal
2. Select Manage products
3. Add a new release
4. Set ‘supported devices’ appropriately based on BlackBerry Q10, BlackBerry Z10 and/or BlackBerry PlayBook support for your app. If the app supports more than one device you can choose to select multiple devices for the same release build (BAR file). On the contrary, you can also upload specific file bundles (BARs) for each BlackBerry 10 device.

Supported BlackBerry 10 devices within the BlackBerry World vendor portal

We spent part of last week at BlackBerry Jam Europe, which is generally a conference dedicated to those who already develop apps for BlackBerry. However, there are also many programs for beginners. Since I’ve never created an app, I decided to take a run at developing an app for the Inside BlackBerry Blog. As I have literally no experience developing apps, I asked Alex and Luke for some help.

We used the BlackBerry App Generator to automatically pull content from the Inside BlackBerry Blog, and the BlackBerry Facebook and BlackBerry YouTube pages. It took us only about 10 minutes from start to finish and it was absolutely free. The result is a great-looking app that pulls in all of our articles, posts and videos. Let’s have a look as Alex walks us through the process.

[ YouTube link for mobile viewing ]

See how easy it was? Using the BlackBerry App Generator you could have your own app up and running in just a few minutes, even with no development experience. Do you have a blog or content and think it would make a great app? Give the BlackBerry App Generator a try for yourself and let us know.

BlackBerry World 4.3 changes the BlackBerry World search algorithm to help make the discovery of your app or game easier for customers. To take advantage of these changes, we wanted to share with you how the following product attributes are prioritized to determine search results. The attributes are listed in order of importance to the algorithm:

1. Product Name
2. Keywords
3. Vendor Name
4. Short Description

It is important to note that the Long Description is no longer considered by the Search algorithm.

Product Name

The most important product attribute is the Product Name – the title of your application shown to the Consumer. Product Names can be specified by Platform and Language. This could allow you to have:

• ‘Awesome App” for BlackBerry 10
• “Awesome App HD” for BlackBerry PlayBook

Keywords

Keywords are the second most important attribute in determining search results and provide new flexibility and creativity to get your product noticed. Introduced to the BlackBerry World Vendor Portal in 2012, Keywords will now be used to determine search results. Keywords can be specified by Platform and Language.

Changing the Keywords from the Vendor Portal takes effect between one and nine hours after saving the changes.

• Number of Keywords.  There are up to ten (10) Keywords per Platform and Language pairing.
  • For example, the BBOS Platform for French has up to 10 Keywords and the BBOS Platform for English has up to 10 keywords
• Maximum Length of a Keyword: Each Keyword cannot be more than 100 characters or 3 words long.
  • For example, “Built For BlackBerry”
• Maximum Length of ALL Keywords for a Platform/Language Pair: There is a 1,000 character maximum length for all the Keywords per Platform and Language pair.
  • For example, the BBOS Platform for French has a 1,000 character maximum and the BBOS Platform for English has a 1,000 character limit.
• Term Frequency within Keywords – the number of times a term appears in the keywords increases the relevance.
  • For example, having “Black” 5 times within the Keywords gives more relevance than having “Black” only once.
• Term Proximity – for multiple search terms, say A and B, the keyword where A is closer to B has higher relevance over keywords where A is further from B. For example:
  • Given:
    • App #1 with Keyword = Built for BlackBerry
    • App #2 with Keyword = Built for the BlackBerry
    • Consumer search = “Built BlackBerry”

• WHY? The number of characters between Built and BlackBerry is less in App #1’s keyword than in App #2’s.
• Relevance – the keywords must be relevant to the product
  • Keywords cannot be competitive products or other product names.
  • Keywords cannot be popular terms for the sake of receiving a high hit rate.

Vendor Name

The third most important attribute is Vendor Name.

Short Description

The least important attribute is Short Description. It is also available by Platform and Language pairing.

Head over to BlackBerry World Vendor Portal and update your app today!

“PANIC!!!” you might think.

Well, luckily you found this blog post. I am going to walk you through the all the steps you need to get this working, so buckle up and sit tight, because the clock is ticking.

Step one:

Add Q_DECL_EXPORT in front of your main method, so it looks like this:

Q_DECL_EXPORT int main(int argc, char **argv)

Step two:

Nope, that’s it.

We added that requirement in the Gold SDK and added it to the template then, so if your project was created afterwards it’s already taken care of.

If you are still having problems, make sure you aren’t writing to the assets directory, as it’s read-only on release builds. If you want to change something there, copy it to the data folder first.

Anyway, the Q_DECL_EXPORT change was part of Project Zygote, so if you are running into this error you might want to go all the way through the process  and get a big start time decrease for your app. Again, apps built with the Gold SDK have already had this done for them. Don’t let those newbies show you up!

Good luck! We’re almost there!