(This is a guest post by Stefan Tsokev - a Telerik Senior Enterprise Support Officer.)

Many users have asked us how to make their app recognize a certain url scheme and react on it. Of course opening a mobile application from another mobile application is a valid scenario and as we did not find straight-forward information on the net how to accomplish this (especially when it comes to Android platform), we decided to make a post about it.

Handling URL requests in iOS

For an iOS app, you can add a URL Scheme handler in your app's Info.plist (see Edit Configuration Files) so that your app launches when another iOS app (like Mobile Safari) launches a URL with your custom scheme.

1. Register your custom scheme in your app's Info.plist: the instructions are here. The required markup comes down to this:

    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLName</key>
        <string>com.telerik.myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>myapp</string>
        </array>
      </dict>
    </array>
   

2. Thanks to the Apache Cordova team, you are able to add a global handleOpenURL function in your JavaScript which just takes one parameter – a string containing the URL that was launched. Add your code to parse and handle the URL inside that global function. This function is always called if your app was launched from the custom scheme.

    function handleOpenURL(url) {
        // TODO: parse the url, and do something 
    }
   

Handling URL requests in Android

For an Android app, you can add an intent filter in your app's AndroidManifest.xml (see Edit Configuration Files) so that your app launches when another app (like Chrome browser) launches a URL with your custom scheme.

1. Register your custom scheme in your app's AndroidManifest.xml: the instructions are here. The required markup comes down to this:

    <activity ....>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="myapp" />
        </intent-filter>
    </activity>
   

2. Download and add the WebIntent Cordova plugin to your project. The plugin is not plugman compatible at its current state and cannot be used directly in Icenium project. We have made the necessary modifications to it, so it would work in Icenium project targeting Cordova 2.7 (you can download the modified plugin from the sample app). You can find the required modifications in these help articles:

   • Modify the Directory Structure of the Custom Plugin
   • Modify Plugin.xml

   This is how the plugin structure and plugin.xml should look at the end:

3. We use the getUri method of the window.plugins.webintent object which takes a single parameter – a string containing the URL that was launched. Add your code to parse and handle the URL in the callback passed to getUri.

    function handleURLAndroid() {
        window.plugins.webintent.getUri(function(url) {
            // TODO: parse the url, and do something 
        });
    }   
   

How about a query string in the url schema

Sure, that wouldn't be any different than any other url we have worked with. Let's say the app would be launched by the following hyperlink:

<a href="myapp://views/navigate.html">Open App</a>

where views/navigate.html is a view to which we would like to navigate upon starting the app. The url we receive as a parameter isn't directly useful, so we would need to get the path in which the app is executed, the querystring and then use these to put together a correct url. Here is an example

if (url !== "") {
    var appPath = window.location.href;
    var path = appPath.substr(0, appPath.lastIndexOf("/") + 1);
    var queryString = url.substr(url.lastIndexOf("//") + 1, url.length);
    var activeurl = path + queryString;
    window.location.href = activeurl;
}

Sample Code

If you'd like to see this in action, feel free to clone the sample-custom-url-scheme app from github or from Graphite/Mist samples (Clone -> Sample Projects). Remember that this app would launch only when another app launches a URL with the custom scheme.