Porting Your Existing Construct 2 Application to BlackBerry 10 (WebWorks SDK 2.0+)

by Retired on ‎12-13-2013 09:06 AM - edited on ‎01-24-2014 11:04 AM by BlackBerry Development Advisor (1,696 Views)

If any errors are found or questions arise, please feel free to comment on this KB or contact eoros@blackberry.com directly.

 

The information within assumes familiarity with Construct 2, up to the point that you are able to develop your application and are now ready to export your project for various platforms.

 

For information on developing with Construct 2, please refer to the following.

 

BlackBerry WebWorks SDK 2.0

 

You can download the most recent version of the BlackBerry® WebWorks™ SDK 2.0 here:

https://developer.blackberry.com/html5/download/

 

This will enable a number of command-line interface (CLI) tools that you can use to register your code signing keys and make available the WebWorks command, enabling you to create new projects, deploy to devices, and build release versions of your application.

 

For those familiar with PhoneGap™, BlackBerry WebWorks 2.0 is similarly a Cordova™-based product. The benefit of using the BlackBerry WebWorks SDK 2.0 is that your environment is automatically configured to build for BlackBerry® 10 devices without the need for any additional configuration. Both Cordova and PhoneGap are valid tools, although you will need to follow the corresponding platform guides to configure your development environment should you choose that route.

 

For more Information on BlackBerry WebWorks 2.0, please see the following.

https://developer.blackberry.com/html5/documentation/beta/differences_between_ww_and_ww20.html

 

Code Signing Keys

 

If you have already registered your BlackBerry Code Signing keys, you do not need to take any action. BlackBerry Code Signing is transitioning to be completely BBID-based so, if you have not yet made the switch, you are encouraged to do so (though not required at this time.)

 

If you have not yet registered any BlackBerry Code Signing keys, you will need to do so.

 

In either case, instructions can be found here:

https://developer.blackberry.com/html5/documentation/beta/testing_and_signing_setup.html

 

Exporting For BlackBerry 10

 

At this point, there are three assumptions. You have:

  1. Installed the latest BlackBerry WebWorks SDK 2.0.
  2. Configured your BlackBerry 10 Code Signing keys.
  3. Developed your Construct 2 application.

Now, you are at the point of exporting your Construct 2 application for the BlackBerry 10 platform. To do so, we will need to begin in the command-line. On your PC, open a command-line terminal and navigate to the folder where you would like to create your project. For this example, we will be using c:\webworks.

 

C:\>cd webworks

C:\webworks>

 

From here, we want to create a new WebWorks project that will house our Construct 2 application. For this, we use the webworks create command, and then we'll navigate into our newly created folder.

 

C:\webworks>webworks create C2Sample

C:\webworks>cd C2Sample

C:\webworks\C2Sample>

 

This will generate a pre-populated, sample folder structure for your application. We'll want to navigate to the following sub-folder and delete everything except config.xml. Only config.xml should remain.

 

C:\webworks\C2Sample\www

 

Next, let's switch over to the Construct 2 IDEFrom the Construct 2 IDE, we'll want to click through the following.

 

File > Export Project... > Web (HTML5 Website)

 

The export option for Mobile (BlackBerry 10) refers to the legacy BlackBerry 10 WebWorks SDK 1.0.

 

In the Export Options dialog, for Export Files To, choose the www sub-folder of your WebWorks project; this is the same folder from which we previously deleted the default files.

 

C:\webworks\C2Sample\www

 

The remaining items can remain as they are, though you may wish to enable Minify Script for production releases. Once configured, click Next.

 

In the HTML Export Options dialog, you can choose the option that best fits your project. If you are unsure, choose Embed Style. Once configured, click Export.

 

This should generate your Construct 2 application within your BlackBerry 10 WebWorks project folder; specifically the www sub-folder.

 

Update config.xml

 

Before you can build your project, we will need to make a few changes to the config.xml file in our root www folder. Example:

 

 

C:\webworks\C2Sample\www\config.xml

  

You can open this file with any standard text editor. The default values that will need to be changed are highlighted in blue below.

 

 

<?xml version='1.0' encoding='utf-8'?>
<widget id="webworks.default" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>WebWorks Application</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@callback.apache.org" href="http://cordova.io">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <access origin="*" />
    <preference name="fullscreen" value="true" />
    <preference name="webviewbounce" value="true" />
</widget>

  

  • id: This should be unique to your application. A reverse-domain format similar to com.vendorName.applicationName is recommended.
  • version: Change this to the current release version of your application. For test builds, you can leave this as-is.
  • <name>: The application name that will be displayed on the device's homescreen.
  • <description>: A description for your application.
  • <author>: Your email, website, and name. Email and website are optional.

Also, take note of the <access> element. If your application is loading resources from external locations, you will need to white-list those URLs. For more information on <access> and various config.xml elements, please check the following documentation.

https://developer.blackberry.com/html5/documentation/beta/modifying_your_config_file.html

 

Building and Deploying a Debug Version

 

To test your newly exported project on a BlackBerry 10 device:

  1. Switch your device to Development Mode by navigating: Settings > Security and Privacy > Development Mode > Development Mode: On.
  2. Connect your device to your PC via USB.
  3. Execute the webworks run command from the root folder of your WebWorks project, using the CLI.

  

C:\webworks\C2Sample>webworks run

  

You should be prompted for your Device Password, after which the WebWorks SDK will create and deploy a debug token, uninstall any previous versions of the application, and install the current project in debug mode; enabling Web Inspector automatically.

 

Building a Release Version

 

To release an application through the BlackBerry® World™ storefront; it must be fully signed. To do so, execute the following command from the root folder of your WebWorks project, using the CLI.

 

C:\webworks\C2Sample>webworks build --release --keystorepass 123456 --buildId 25

Where 123456 should be replaced with your own Code Signing password, and the buildId should reflect the current version of your application. Most developers will begin at 1 and increment with each new release.

 

The buildId is combined with the version specified in your config.xml. For example, if your config.xml version is 1.0.0 and your buildId is 25, the full version of your application will be 1.0.0.25. When submitting to BlackBerry World, new releases must have a higher version than the previous release. You can achieve this by either increasing the version in config.xml, or by incrementing your buildId.

 

Note that 2.0.0.1 is a higher version number than 1.2.3.25.

 

WebWorks API Plugins

 

For information on including BlackBerry® Messenger and In-App Payment plugins in your Construct 2 applications, please refer to this GitHub® page:

https://github.com/blackberry/Construct2Plugins/tree/WebWorks-2.0