Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

How To - Create a URL Launching Application for BlackBerry 10

by Retired ‎05-05-2014 01:56 PM - edited ‎05-05-2014 02:02 PM (4,083 Views)

Applies To


  • BlackBerry® 10.1+
  • BlackBerry® WebWorks SDK

For information on creating a launcher application for the BlackBerry® PlayBook™ tablet, please refer to this document:



For information on creating a launcher application for legacy BlackBerry® OS devices, please refer to this document:





BlackBerry 10 offers a wide variety of ways to create a mobile application. Often, organizations or individuals will already have a mobile website that they're looking to deploy to BlackBerry 10 but want to minimize the effort in rewriting code, or simply want to gauge interest before developing a full-fledged application.


On BlackBerry 10, it's easy to create an application that simply launches an external URL, allowing you to deliver your mobile experience in the form of an application.


The main benefits of this approach include:

  • Discoverability: You can deploy and market your application through the BlackBerry World storefront.
  • Usability: The application exists on the device home screen.
  • User Experience: The application is launched in its own container, not in the Browser application, which can detract from the overall experience.
  • User Interface: Every pixel on the screen is dedicated to your application's content; no additional toolbars or navigation panes.



BlackBerry WebWorks SDK


Download and install the latest version of the BlackBerry WebWorks SDK from the following location:



During the installation, be sure to install start menu shortcuts for ease of access. Once installed, you will need to download and configure your Code Signing keys.


Code Signing


Create a BlackBerry ID (if you haven't already) and download your BlackBerry 10 Code Signing token to your PC from the following location:



Once you download bbidtoken.csk, you can launch the WebWorks GUI. Example (Windows):


Start > BlackBerry > BlackBerry WebWorks SDK

This should launch a web server and open your browser to the WebWorks management console.




Click on the Certificates panel to view the Code Signing registration tool.




Populate the Signing Token Location field with the path to your own bbidtoken.csk file and click Replace Signing Key. This should register your key and you can view where it was installed under the Developer Certificate Location path.


Once your Code Signing token has been registered, you are ready to create your launcher application.


Creating Your Launcher Application


Click the + icon in the Recent Projects pane to create a new project.




Fill in the fields as follows:

  • Project ID: A unique, reverse-domain URL that will identify your application.
  • Project Name: The user-friendly version of your application name.
  • Project Path: The path where you want your application to be created.

Once complete, click the Create button.


Under your newly created application, select the Configuration pane.




In the Configuration screen, there are a number of optional values to fill in, but the most basic configuration for a launcher application will need the following:


Icon > Source

Your icon should be 114x114px and you need to provide a path relative to your www folder. For example, if my path was icon.png, then it would refer to an icon located on my file system as follows.


C:\Users\eoros\WebWorks Projects\Project1\www\icon.png


Splash Screen > Source

Similar to the Icon, you will need a relative path to your www folder. Depending on the devices you are deploying to, you can add multiple splash screens.

  • 720x1280px (BlackBerry Z30 and Z3)
  • 768x1280px (BlackBerry Z10)
  • 720x720px (BlackBerry Q10 and Q5)


Main URL

This is the most important piece as it determines what to show when the application launches. By default it will refer to index.html. You will want to change this to reflect your own external URL. Example:




Access List > Origin

This is the second most important piece. In order to actually allow your launcher to reach out to external URLs. For the example above, you would need to white-list the following origin, with Allow subdomains enabled.



 This would whitelist:

  • http://www.domain.com/index.html
  • http://subdomain.domain.com/something/and/more.html
  • And many other variations of domain.com.

Note that if you are using both http and https, you will need to whitelist each individually.



You will need to whitelist every protocol (http, https) and domain combination that your application will be accessing. If you are not able to whitelist every combination (i.e. some domains may not be known), you can disable the Enable Web Security option.



Additional Considerations

Other values you may want to consider filling in are:

  • App Description
  • Author
  • Author Email
  • Author URL

Once complete, Save your Configuration. Once saved, you are ready to build your launcher application for deployment.



In your project's www folder, you can actually remove all files (except config.xml) and your launcher application will still function since all HTML5 content is being loaded externally.



Building Your Launcher Application


Building your application will take the files you have created, specifically your Configuration file, and will create a BlackBerry Archive (BAR) file that you can deploy to a device for testing, or distribute through the BlackBerry World storefront.


In the WebWorks management console, switch to the Build pane for your project.




You can use this screen to build your application and test on a device (via Build & Install if the device is connected to your PC via USB), or build in Release Mode to get a BAR file to deploy to the BlackBerry World storefront.

Users Online
Currently online: 33 members 847 guests
Please welcome our newest community members: