Headless Apps 101

The recent introduction of headless apps in BlackBerry 10 has generated phenomenal interest among developers. You also had a lot of questions around headless apps that need to be answered, so as a follow up to my first article, Rise of the Headless Apps, I am back again to answer some popular questions and also to walk you through how to create a simple headless application.

Types of Headless Applications

First off, there can be two types of headless applications – long running and short running. The type determines how long a headless application can run each time it gets launched (more on getting launched later). The life of a short running headless app is 20 seconds long, and a long running headless application is free to run indefinitely from the time it launches. Determinig whether your app should be long or short running is an important decision. Short running applications are ideal because the device can run more efficiently. However, if 20 seconds isn’t enough, then write a long running app; just be sure to apply for special permission via the App Permissions Request form. Otherwise, you will NOT be able to properly sign long running headless applications.

Structure of a Headless App

A headless application is a package of two separate application projects packaged in one bar file. One is responsible for the UI part of your application that gets launched when the user clicks the application icon on the homescreen. The other is responsible for the headless service (either short running or long running). Note that you MUST always have a UI entry point in your headless application package, because headless application packages will still have an icon on the home screen and the system needs a UI entry point to launch when that icon is clicked. That way, the user can always stay in control of the app.

When do headless applications get launched?

A headless application can be launched in two ways. It can either get invoked by the system on certain system events (aka triggers), or by any UI application including the UI entry point of your headless application package. Essentially, you define invoke targets for your headless entry point that the system or a UI app can invoke.

Note that a headless process cannot invoke UI applications.

What system triggers are currently available?

If you choose to have your app launched by the system based on certain system events, we currently have four triggers available:

• system.STARTED: Triggers your headless application on device startup, or as soon as the app gets installed. Common use cases are long running headless apps that run 24/7, or a short running headless app that needs to perform some initializations/registrations when the device starts up.
• PORT_DIRECTED_SMS – Triggers your headless application when an SMS message arrives on a custom port that your app registered for. Note that this is not meant for SMS messages that appear in the regular sms inbox.
• GEOREGIONEXIT and GEOREGIONENTER – Triggers your headless application when a gefence enter or an exit event occurs for the fences your application registered for.
• PUSH – Triggers your headless application when a push message arrives.

This is only the first batch of triggers that shipped with 10.2. We are actively tracking trigger requests based on their popularity and are committed to bring more triggers in the future.

Great! So how do I build a headless app?

While it is true that there are a number of steps involved in creating headless apps, I can assure you that it does not involve a lot of coding. Whether you are building a new app or you are converting an existing app to headless, the following steps should clearly show exactly what you need to do to create the skeleton for a headless application:

1. Create the headless project
2. Modify the project structure
3. Create the UI project
4. Add assets
5. Modify entry points
6. Specify the appropriate permissions
7. Add invocation framework support for triggers
8. Build and install the app

That’s it! For more details, head straight to our all new documentation page for headless apps. We also created templates for headless apps built right in to the IDE so that you don’t have to go through these steps manually, but for our deeper understanding, let’s go over what the template does for us.

Sample Applications

Reading documentations are great (assuming we do), but nothing comes close to real sample applications that we can download and run out-of-the-box. With that in mind, we created sample apps to demo different aspects and use cases of headless apps. The following samples are currently available in our github repository, and there are a few more on the way.

Where are headless apps supported?

Short running headless applications are supported on all devices running 10.2. If you are planning to develop a long running headless app, you can do so using the latest 10.2 developer build posted here. However, we have decided to only approve long running headless application submissions on BlackBerry World for 10.2.1.

That’s all from me for the day and I hope I have answered a lot of the questions you had on this topic. If I missed anything, please hit me on the developer forums or @shadidhaque. Happy coding and let’s lose the heads!