BlackBerry 10

---

URL handling on BlackBerry 10 devices works for Cascades apps through BB10's invocation framework.

Registering a URL scheme

To configure a BlackBerry 10 app to handle a URL scheme, you must edit the app's bar-descriptor.xml file. There, add an invocation target and a target filter.

Invocation target

A BB10 invocation target specifies the application called by an invocation binding, and a user-facing name and icon. If a suitable invocation target isn't already present, add a new target to your app's bar-descriptor.xml file:

<invoke-target id="{element id}">
    <invoke-target-type>application</invoke-target-type>
    <invoke-target-name>{app name}</invoke-target-name>
    <icon><image>{icon}</image></icon>
</invoke-target>

Here, replace {app name} with the user-facing name of your app, and replace {icon} with the filename containing your app's icon. Finally, replace {element id} with a unique reverse-DNS identifier for your app. If you've followed our advice and used a subdomain of your own DNS name for the URL scheme, then reversing your URL scheme should suffice. An invoke-target-type of "application" indicates that you intend to be launched as an application, rather than a BB10 card.

Target filter

Aside from registering URL schemes, target filters can also filter by MIME type or file extension. As such, target filters have many attributes not needed here. To register as the handler for a URL scheme, the following to your app's invocation target:

<filter>
    <action>bb.action.VIEW</action>
    <action>bb.action.OPEN</action>
    <mime-type>*</mime-type>
    <property var="uris" value="{scheme}:"> </property>
</filter>

Here, replace {scheme} with the URL scheme that you selected. One of the action values bb.action.VIEW or bb.action.OPEN should match any attempt to visit a URL, and the uris property will match the beginning of your native URL. For more on how target filters are matched to invocations, see the BlackBerry 10 documentation.

Example

To the file bar-descriptor.xml in our Grid6 app, we would add the following XML:

<invoke-target id="org.appurl.grid6">
    <invoke-target-type>application</invoke-target-type>
    <invoke-target-name>AppURL Light Grid</invoke-target-name>
    <icon><image>logo.png</image></icon>
    <filter>
        <action>bb.action.VIEW</action>
        <action>bb.action.OPEN</action>
        <mime-type>*</mime-type>
        <property var="uris" value="grid6.us:"> </property>
    </filter>
</invoke-target>

Handling URLs

Now that the OS knows to invoke your app when visiting specific URLs, you must prepare your app to handle those invocations. The following code will listen for invocations.

In your app's main():

MyApp app // MyApp is a subclass of bb::cascades::Application

// ...

InvokeManager invokeManager;
QObject::connect(&invokeManager, SIGNAL(invoked(const bb::system::InvokeRequest&),
    &app, SLOT(onInvoke(const bb::system::InvokeRequest&)
);

In your definition for MyApp, override the onInvoke function:

void MyApp::onInvoke(const bb::system::InvokeRequest& req) {
    // handle invocation request...
    QUrl url = req.uri();
    // ... handle things ...
}

For instance, in Grid6 we have:

// in main():
bb::system::InvokeManager invoke_mgr;
QObject::connect(&invoke_mgr, SIGNAL(invoked(const bb::system::InvokeRequest &)),
                 &app, SLOT(invoke(const bb::system::InvokeRequest &)));
new Grid6(&app);

// in Grid6.hpp:
class Grid6 : public QObject {
    Q_OBJECT
public:
    // ...
    Q_SLOT Q_INVOKABLE void invoke(const bb::system::InvokeRequest &);
};

// in Grid6.cpp:
void Grid6::invoke(const bb::system::InvokeRequest & req) {
    setStateFromUrl(req.uri());
}

Http-triggered app launching

Since not all platforms have native support for launching apps with http links, AppURL's recommendation for http-triggered app launching is to implement it wherever possible, while maintaining AppURL compliance through URL schemes and appurl.json files. Therefore, we strongly recommend you implement http scheme filtering in your BlackBerry 10 apps.

In Grid6, we can handle the right http URLs by changing the property value in the filter tag of our BAR descriptor to:

<property var="uris" value="grid6.us:, http://grid6.us/"> </property>

After this change, our native app will handle requests to http links.

For more information, see the invocation framework docs.

Visiting a URL from a BlackBerry 10 app

To visit a URL from inside a BlackBerry 10 app, launch an unbound invocation request to that URL. This code visits the URL "grid6.us:/xyzzy006":

InvokeManager invokeMgr;
InvokeRequest req;

req.setUri(QUrl("grid6.us:/xyzzy006"));
InvokeTargetReply *reply = invokeMgr.invoke(req);

To get these names, the current namespace should have included InvokeManager, InvokeRequest, InvokeTargetReply, and QUrl.