Android

---

URL handling on Android devices works through intents. Intents let apps register themselves to get launched in response to certain specified actions, and URL opening is one of these actions.

Registering a URL Scheme

To register an app as a handler for a URL scheme, we need to add an intent filter to the app's manifest. To do so, we need to know the family of URLs we want to register, and the fully-qualified component name of the activity that will handle the URL. Here, we say that the URL handler us.grid6.HandleURL will handle URLs with the scheme grid6.us.

In the app's manifest, AndroidManifest.xml, we add a new activity to our app's application entry:

  <activity xmlns:android="http://schemas.android.com/apk/res/android"
            android:name="us.grid6.HandleURL"
            android:label="Grid6">
    <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="grid6.us" />
    </intent-filter>
  </activity>

Let's break down these tags:

activity

A description of the entire Android activity. The activity tag starts with a namespace declaration (xmlns:android=...). If the namespace directive defining android is already in some enclosing tag (it probably is), then you don't need to define it again here. The name attribute is fully-qualified component name of the activity that we want to call. The label attribute is the name of your URL handler. The user will see the value of label when asked how to open your URL, so ensure that it is clear and comforting.

intent-filter

The set of intents that this activity should handle.

action

The action this intent provides. For a URL-handling intent, this must be VIEW.

category

The categories this intent filter covers. The categories BROWSABLE and DEFAULT should be supplied by an URL-handling intent. BROWSABLE is the usual URL-visiting category, and DEFAULT is automatically added to intents in many situations that you want to handle. (When the DEFAULT category isn't present in an intent, the intent will still match this filter.)

data

Here, the specific family of URLs to handle. To handle a URL scheme, you only need to specify the scheme attribute. If you want to be more discerning, and capture only some of the URLs at your selected scheme, you can specify a host value, and path, pathPrefix, or pathPattern. For more details, see the Android manifest documentation.

So, once a user installs the Grid6 app, every time they visit a URL with the grid6.us scheme, they will have the choice to open the URL in this app through the standard intent dialog. When they open this app, it'll call the us.grid6.HandleURL activity, which can then handle the URL however fits.

Handling a URL Scheme

Inside an Activity, you can call getIntent() to retrieve the intent that launched that Activity. If the intent was to visit a URL (i.e., intent.getAction() == Intent.ACTION_VIEW), then intent.getData() will return that URL.

To further structure your URL handling, you might consider employing a URL-routing library like Routable.

Visiting a URL from an Android app

To visit a URL from inside an Android app, launch an activity with an intent to view the URL. This code visits the URL "grid6.us:/xyzzy000":

Intent url_intent = new Intent (
    Intent.ACTION_VIEW,
    Uri.parse("grid6.us:/xyzzy000")
);
intent.addCategory(Intent.CATEGORY_BROWSABLE);
startActivity(intent);

This must be in a file that imports android.app.Intent and android.net.URI.

Note: In order to make URLs cross-platform, a custom URL scheme must be used, as not all platforms support opening apps with HTTP links. At AppURL.org, however, we believe that opening apps with HTTP URLs is the future, and therefore we strongly recommend that you implement HTTP scheme filtering for opening apps as well. For more information, take a look at the Android Intent docs.

Typing a URL into a browser

When a user enters a URL into the Android browser's location bar, the browser tries to handle the URL itself, instead of launching your app. Unfortunately, the browser doesn't issue a general-purpose VIEW/BROWSABLE intent when you type a URL into the location bar. It will launch your app, though, if you visit a link to your app in the page, or if a script on the page redirects the browser to your app.