Porting AIR apps to WebWorks

With the end of support for the Adobe AIR runtime on BlackBerry 10 OS version 10.3.1, one way to keep your app available on BlackBerry 10 is to port your AIR app to HTML5, the development language of BlackBerry WebWorks apps. With your app refactored in HTML5, you can use the BlackBerry 10 WebWorks SDK to package the app as a .bar file.

Although the BlackBerry Runtime for Android apps continues to support AIR apps packaged as Android apps, in some cases, converting your app to HTML5 and creating a WebWorks app may be the only migration path available.
  • If your AIR app uses any AIR Native Extensions (ANEs) to extend the capabilities of the AIR runtime, then only by converting to a WebWorks solution can you achieve the same level of functionality. The Android runtime does not permit ANEs to connect with the BlackBerry native APIs.
  • If your app is deployed within the work perimeter, then a WebWorks solution is the only viable alternative, since Android apps are not permitted within the work perimeter.

Porting your AIR app to HTML5 actually provides a couple of additional built-in benefits:

  • HTML5 apps offer greater cross-platform compatibility than AIR apps. Most mobile platforms support HTML5 apps to varying degrees, while AIR apps are only supported by Android devices, and on BlackBerry devices as Android apps.
  • HTML5 apps are more future-proof than AIR apps. HTML5 is quickly emerging as the future of web development.

Before you begin

If you are new to BlackBerry WebWorks, before you start to port your app, look at the Getting Started section of the WebWorks documentation to get information on:
  • What a WebWorks app looks like
  • What you can expect to receive as part of the BlackBerry 10 WebWorks SDK
  • How to get the tools and how to set up your computer to use them
  • How to create a WebWorks project
  • How to create a basic HelloWorld app

Convert your Flash content to HTML5

Although BlackBerry doesn't offer tools to assist with Flash conversion, there are several third-party options available. Some Flash-to-HTML5 conversion options include:

  • PixelPlant: PixelPlant is a service that converts your .swf files to HTML5 for you. You upload your Flash content, and they return it in HTML5 format. For more information, see pixelplant.com.
  • CreateJS: CreateJS is a suite of JavaScript libraries that are designed to create rich content and animations using HTML, CSS, and JavaScript. Because the CreateJS libraries are modeled after Adobe ActionScript APIs, much of the scripting logic can be reused with only minor changes. For more information, see createjs.com.

There may be other options that are better suited to your needs. You should thoroughly investigate all options and determine which one works best for you. In any case, you should be prepared to make at least some manual changes to your content to make it HTML5-ready.

Create a BlackBerry WebWorks project

If you haven't done so already, download and install the BlackBerry 10 WebWorks SDK (for additional information about the tools you need and how to set them up, see Setting up your system).

Once it is installed and set up, use the BlackBerry 10 WebWorks SDK web tool to create a WebWorks project:

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Click [+] beside the Projects heading in the navigation panel.
  3. In the Project Name field, enter a name for your project. The project is identified within the web tool with this name.
  4. In the Project Path field, enter a project path. This path specifies the folder location where your project resources are stored.
  5. Click Save.

Your new project is created with a complete set of template resources that you can build into a functioning app.

Add your HTML5 resources to your WebWorks project

Once you've converted your Flash content to HTML5 and created your WebWorks project, you need to add your HTML5 content files to the WebWorks project folders.

To add your HTML5 content to your WebWorks project:

  1. In your WebWorks project folder (which you defined in the Project Path field when you created your project), locate the www folder.
  2. Delete the template project resources in the www folder and its subfolders and paste your HTML5 content and other app resources in their place. Make sure that files are copied to the correct locations:
    • HTML files should be copied to the www folder.
    • CSS, JavaScript, and image files should be copied to the appropriate subfolders of the www folder.

Rebuild your AIR Native Extensions as Cordova plugins

If you used AIR Native Extensions in your AIR app, there is no direct path for porting those extensions to WebWorks. You must rebuild your ANE as a custom Cordova plugin.

WebWorks actually provides greater access to the native features of the BlackBerry 10 OS than the AIR runtime. Before creating a custom plugin, check the existing plugins installed with the SDK to see if they provide access to the features you need. In addition, members of the WebWorks community have also made custom plugins available that may achieve what you need. You can see the complete list of standard and community-created plugins in the Cordova plugins registry by searching for plugins with the com.blackberry prefix.

If you do need to create a custom plugin, there are a few resources that can help you:

Add plugins to your project

If you are primarily an AIR or Flash developer, the concept of plugins may be a little foreign. In a WebWorks app, a plugin provides a set of APIs, together with the bindings between JavaScript and the native C/C++ layer of the BlackBerry 10 OS. In Apache Cordova, upon which BlackBerry WebWorks is built, all communication with the native layer is encapsulated in a number of plugins. Because of this architecture, you need to add a plugin for each of the BlackBerry WebWorks APIs you want to access within your app.

To add a plugin to your project using the BlackBerry 10 WebWorks SDK web tool:

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Navigate to your project and click Plugins.
  3. Enter the ID or URL of the plugin in the Plugin Name or URL field.
  4. Click Add Plugin.

Set configuration settings for your project

You can define aspects of your app, such as its orientation or background color, by configuring your app preferences. You can configure your app preferences using the BlackBerry 10 WebWorks SDK web tool, or you can edit the config.xml file. For information on editing the config.xml file, see Modifying your config.xml file.

To set your app preferences with the BlackBerry 10 WebWorks SDK web tool:

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Navigate to your project and click Config.
  3. Complete the fields for the preferences you would like to set. For a complete description of all the configuration settings, see Configuring your app preferences.

Build and test your app

With the previous steps completed, you can begin building and testing your app to make sure that it functions as expected. You can test your app using either a BlackBerry 10 device or the BlackBerry 10 Device Simulator.

For now, we'll test the app using the simulator.

If you have a BlackBerry 10 device, you can install and run your app directly on the device by following the steps outlined at Deploying your app to a device.

Before you begin:
  • Make sure the BlackBerry 10 Device Simulator is installed and running on your computer. If you haven't already downloaded it, you can get the simulator here.
  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Navigate to your project and click Build.
  3. Select Debug Mode.
  4. Select Simulator.
  5. Enter the device password used by your simulator.
  6. Click Build & Install.

The tool packages your app into a .bar file, installs it on your simulator, and opens it.

When you are satisfied with the app and are ready to sign and distribute it, see Building and signing your completed app.

Last modified: 2014-12-04

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus