Accessing external resources

You can specify that your BlackBerry WebWorks app can access BlackBerry WebWorks APIs for a domain in an executable container. An executable container allows your app to run JavaScript code within the context of a webpage. It can be a page, a frame, or an iframe.

By default, BlackBerry WebWorks apps cannot access data from external resources. For example, a BlackBerry WebWorks app cannot retrieve an HTML webpage, unless you configure the app to allow access.

To allow access to external resources, you must specify access permissions to define the list of domains that your app is allowed to access.

Best Practices: Allowing access to external resources

Whenever your app retrieves content from external resources, consider the following best practices to make it as secure as possible:
  • Provide JavaScript access to sensitive APIs only to trusted and secure websites.
  • Use the same precautions that you would use for a hosted website to protect against users with malicious intent.
  • Protect your communication channel by using HTTPS when you expose sensitive APIs to the domain.

In the following example, we use the access element to specify that the site is accessed over HTTPS:

<access uri="https://somedomain.com" subdomains="true" />

Allowing requests to any website

If your app is designed to access data from an unknown or changing domain, you can use the wildcard character (*) to ensure that your requests are not blocked. For example:

<access origin="*"/>

The wildcard character (*) cannot be used for data accessed by XMLHttpRequest. To access data using the XMLHttpRequest, you must explicitly specify each domain.

When you use the wildcard character (*), webpages that your app accesses cannot access any of the app APIs.

In the example above, all requests that do not access content via XHR and that do not require access to app APIs are allowed.

Whitelisting file requests

If your app is designed to access the device file system, you can define the file:/// scheme as the origin domain to ensure that your requests are not blocked.

Here's how you can ensure that your file system requests are permitted:

<access origin="file:///" subdomains="true" />

Defining external access using the SDK web tool

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. In the left pane, click <your_project> > Configuration.
  3. Locate the Access List section near the bottom of the list of preferences.
  4. In the Origin field, enter the domain you want to allow your app to access. If your app is designed to access data from an unknown or changing domain, you can use the wildcard character (*) to ensure that your requests are not blocked.
  5. To allow access to all subdomains within the specified domain, select Allow subdomains.
  6. Click Add Access.

Adding access permissions to the config.xml file

You can specify access to a domain by adding an <access> element to the config.xml file. The config.xml file can contain multiple <access> elements to specify access to different domains. The <access> element is a child of the top-level <widget> element

To add an access permission to the config.xml file:

  1. Open the config.xml file in the text editor of your choice.
  2. Add an <access> element, specifying the domain you want to allow your app to access. If your app is designed to access data from an unknown or changing domain, you can use the wildcard character (*) to ensure that your requests are not blocked.

    For example, to specify that a site is accessed only over HTTPS, you can add the following entry to your config.xml file:

    <access origin="https://somedomain.com" subdomains="true" />

Last modified: 2014-10-09



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

comments powered by Disqus