Using BlackBerry WebWorks APIs

If you want to use BlackBerry WebWorks APIs, you should note the changes you need to make in the config.xml file. You must specify the name of the API you want to use in your app's configuration file, which is called config.xml. To specify an API, you add a <feature> element to your config.xml file and include the name of the API in the id attribute.

For example, to add a standard system dialog box in your app, you need to use functionality of the Dialog object in the blackberry.ui.dialog API. So, you add the following to your config.xml file:
<feature id="blackberry.ui.dialog">

For every API you want to use, make sure to read the details of the configuration requirements in the BlackBerry WebWorks API reference. The API reference provides the specific <feature> elements you need to include for the API that you want to use.

In general, you do not need to add <feature> elements for APIs that begin with "HTML5" (for example, HTML5 FileSystem, HTML5 Geolocation, and so on).

Additional requirements for BlackBerry 10

  • For each HTML page in your app that uses a BlackBerry WebWorks API (for example, blackberry.identity), you must include a <script> tag that points to the webworks.js file:
    <script src="local:///chrome/webworks.js" type="text/javascript"></script>

    The webworks.js script initializes BlackBerry WebWorks. When you package your app, the BlackBerry WebWorks Packager bundles the latest webworks.js file as chrome/webworks.js automatically.

  • Before you call an API, you must subscribe to the webworksready event:
    document.addEventListener("webworksready", start());

    The webworksready event occurs when webworks.js completes initializing BlackBerry WebWorks.

Sample code

The following sample shows these coding requirements in context. Notice how the webworks.js script is loaded before invoking any BlackBerry WebWorks APIs.

    <input type="text" id="textAppName"/>
    <input type="text" id="textAppVersion"/>
    <b>Test invoke API</b>
    <input type="button" onclick="window.invoke?window.invoke():
        alert('WebWorks is not ready yet');" value="Invoke Browser"/>
    <input type="textarea" id="textbrowser" value=""/>
<script src="local:///chrome/webworks.js" type="text/javascript"></script> 
    function invoke() {
        blackberry.invoke.invoke({target: "sys.browser", 
            uri: document.getElementById('textbrowser').value}, 
            onInvokeSuccess, onInvokeError);
    window.addEventListener("load", function(e) {
        document.addEventListener("webworksready", function(e) {
           document.getElementById('textAppName').value =;
           window.invoke = invoke;
        }, false);
    }, false);
    function onInvokeError()
    function onInvokeSuccess()

Handling events in BlackBerry 10

You invoke the blackberry.event.addEventListener function in your application to listen for events and the blackberry.event.removeEventListener function to stop listening. You do not need to add any configuration settings in the config.xml file to use these functions.

To monitor an event you must add a <feature> element in the config.xml file to specify the name of the API for the event you want to monitor. The following table lists some of the events you can monitor and their corresponding API names. To find out the details of all the events that you can monitor, refer to the BlackBerry WebWorks API reference.

Event API name
  • pause
  • resume
  • swipedown

  • batterystatus
  • batterycritical
  • batterylow


  • invoked


  • connectionchange


Last modified: 2014-10-09

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

comments powered by Disqus