access element

Supported platforms

BlackBerry OS: 5.0 - 7.0
BlackBerry PlayBook OS: 2.0+
BlackBerry 10 OS

Syntax

<access uri="string" subdomains=["true" | "false"] />

Description

The <access> element specifies that a BlackBerry WebWorks application can access external network resources. By default, if you do not specify an <access> element, an application has access to all local resources. Local resources include any resources in the application archive file. If you specify more than one <access> element, the most specific definition is used. For example, if you use http://somedomain.com and http://specific.somedomain.com, the <access> element that uses the first definition (and any features defined under it) is ignored.

If your application makes calls to APIs on an external server, the external server must be declared in the access list. To specify the APIs to access, use the <feature> element.

As a best practice, you should protect your communication channel by using HTTPS when you expose sensitive APIs to the domain. For information about best practices on securing your application, see Accessing external resources.

Parent elements

<widget>

Child elements

Can contain <feature> elements.

Occurrences

Zero or more

Attributes

You can use the following attributes in the <access> element:

Attribute	Description
`uri`	The `uri` attribute defines the web address for the access request. You can specify a wildcard (`*`) for the `uri` to whitelist any domain, but only for domains that do not access application APIs and that do not access content through `XMLHttpRequest`. If the domain requires access to APIs or accesses data through `XMLHttpRequest`, you must explicitly specify the domain in the `uri`. For more information, see Accessing external resources. The `uri` attribute is required for all platforms except the BlackBerry 10 OS.
`subdomains`	The `subdomains` attribute is a Boolean value that specifies whether the host component in the access request applies to subdomains of the domain that is specified in the `URI` attribute. This attribute is optional. By default, if you do not specify the value of the `subdomains` attribute, the value is set to `false` and no access to subdomains is requested.

Attribute

Description

uri

The uri attribute defines the web address for the access request.

You can specify a wildcard (*) for the uri to whitelist any domain, but only for domains that do not access application APIs and that do not access content through XMLHttpRequest. If the domain requires access to APIs or accesses data through XMLHttpRequest, you must explicitly specify the domain in the uri. For more information, see Accessing external resources.

The uri attribute is required for all platforms except the BlackBerry 10 OS.

subdomains

The subdomains attribute is a Boolean value that specifies whether the host component in the access request applies to subdomains of the domain that is specified in the URI attribute.

This attribute is optional.

By default, if you do not specify the value of the subdomains attribute, the value is set to false and no access to subdomains is requested.

Examples: Allowing access to external resources and APIs

For BlackBerry PlayBook OS and BlackBerry 10 OS:

<access uri="https://somedomain.com" subdomains="true">
  <feature id="blackberry.app" version="1.0.0.0" required="true"/>
  <feature id="blackberry.invoke" version="1.0.0.0" required="true"/>
</access>

For BlackBerry 7 or earlier:

<access uri="http://www.mydomain.com" subdomains="true">
   <feature id="blackberry.pim.memo" required="true" version="1.0.0"/>
</access>