x
x
Oops.
An error occurred.
x
 

URIs and Your Mobile App

Introduction

Allowing your mobile app to be launched via a link is a necessary first step to making it accessible from the web. This enables promotional efforts (email, social posts, ads, etc.) to lead users directly into your mobile app which is typically a better and more seamless experience for your customers. This document explains the mobile app URI concept and best practices for using URIs in your mobile apps.

If your mobile app is already set up to handle a URI, you are all ready to create SPARQ optimized links that detect if the app is present on a user's device and then takes them to the mobile app content they are looking for! You may additionally want to look into advanced features of URI handling, such as deep-linking and install tracking with SPARQ optimized links.

What is a URI?

In short, a URI is really just a link. The most common kind is a web link (http://www.google.com) which when clicked instructs the browser to render a web page. A mobile app URI is another type of link that allows a user to launch an app—not just a browser—when clicked; for example, youtube:dQw4w9WgXcQ will bring up a video in the YouTube app if it is installed. On both iOS and Android, any mobile app can indicate that it handles URIs, and for this reason, URIs are an ideal mechanism by which mobile apps can be launched from the web.

Basic URI Structure

The structure and parts of a URI are set out in Internet Standard STD 66 and RFC 3986, though the Wikipedia article may give a clearer high level overview. In short, a URI contains the following parts:

Example URI: sparqme://sparq.me/history?style=modern#today

sparqme Scheme Name (Required)
sparq.me Authority (Optional)
/history Path (Optional)
style=modern Query (Optional)
today Fragment (Optional)

Choosing a URI format

For a reliable and smooth user experience, it is imperative that you select a URI format that will never be used by a different app. Conflicts can lead to unexpected and undesired behavior.

It is highly recommended that your URI format use a scheme name derived from your product, company, and/or domain name, and that it is sufficiently specific that it is unlikely to be selected by someone else.

For the purposes of simply launching your app, a URI with only a scheme (e.g. companyname-productname:) will suffice; as you approach more advanced features such as deep-linking, using additional URI components such as the authority, path, query, and/or fragment will be required to pass data within the link to your app.

Adding URI Support to your Mobile App

Android and iOS both provide methods for specifying URI support when building mobile apps for their respective platforms.

Android

The Android URI-handling mechanism for mobile apps is based on its activity application component structure. Any of the activities contained in your app can be declared to be able to handle one or more URI formats via an intent filter. This is done through the AndroidManifest.xml file, where the activities are declared, as follows:

  1. Add an android.intent.action.VIEW intent filter for your main application activity (and/or any others you want launchable via a link).
  2. Add the android.intent.category.DEFAULT category to the intent filter. This means that the intent that launches it can be implicit, and not necessarily requesting your particular activity explicitly.
  3. Add the android.intent.category.BROWSABLE category to the intent filter. This makes the URI usable from the browser/links, and not just other apps on the device.
  4. Specify the criteria for your custom URI in the data element. Android breaks it down, so you can include a scheme, host, path, etc. individually. You should at minimum have a scheme, one that is unlikely to be used by anyone else. Only URIs that match every element you have included in the data element of the intent filter will invoke your activity.

Avoid using URIs with the http scheme, as there can be inconsistent behavior between devices, Android versions, and custom browsers.

Example AndroidManifest.xml

<activity android:name=".UriLaunchableActivity">
  <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="sparqme" android:host="sparq.me" android:path="/app"/>
  </intent-filter>
</activity>

This entry indicates that any URIs of the format sparqme://sparq.me/app/xxx should be forwarded to the .UriLaunchableActivity activity in our app. When the activity is started from an intent matching your specified filter, the URI is contained in the intent for that activity, accessible via the getIntent() method. You do not need to handle it explicitly, in which case your activity would run normally as if the user had started it, for example.

For more advanced applications—such as deep-linking—your app may parse details in the URI to extract information about more specific actions, typically in theonCreate() or onStart() callbacks, e.g. to bring up a dialog or invoke a certain feature for the user.

See the Android documentation on intent filters for more details: http://developer.android.com/training/basics/intents/filters.html#AddIntentFilter

iOS

URI support is declared on an application-wide level in the app’s Info.plist file. The CFBundleURLTypes key (shown as “URL Types” in XCode) contains information on the type(s) of URIs your app can handle and would be launched to display, on a scheme basis.

Example info.plist (XML)

<key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleURLName</key>
      <string>com.sparqcode.sparqeye</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>sparqme</string>
      </array>
    </dict>
  </array>

The same Info.plist entry In XCode editor:

Ios_url_types_sample_screenshot

This entry indicates that our app handles URIs with the sparqme scheme. This means that iOS will launch our app any time a link using it is opened, e.g. from Safari, including sparqme:sparqme://sparqme://www.sparq.me/, and sparqme://www.sparq.me/mobile/app.

When the app is invoked from one of these links, the app delegate is called with the exact URI that launched it, via the application:openURL:sourceApplication:annotation: method on the app's app delegate. In most cases, simply returning YES and letting your app run as if it were started from the home screen is sufficient; this allows the app to be started from a browser link, basically. For more advanced applications—such as deep-linking—your app may parse details in the URI to extract information about more specific actions, e.g. to bring up a screen or invoke a certain feature for the user.

See Apple’s documentation on adding custom URLs to your iOS app for more details: http://developer.apple.com/library/ios/documentation/iphone/conceptual/iphoneosprogrammingguide/AdvancedAppTricks/AdvancedAppTricks.html#//apple_ref/doc/uid/TP40007072-CH7-SW50

Advanced Features

With some moderate investment in development effort, your mobile app can be prepared with some highly useful advanced features for improving user experience, and enabling of tracking of app and link performance.

Deep-Linking

Deep-linking is the next step in creating useful mobile app-enabled links. By allowing the URI to include data on what the app is supposed to do, links can now be created to drive the user to a specific function. For example, the Twitter mobile app supports the following deep-linked URIs:

Brings up the profile/timeline of the specified user
Brings up the user's timeline
Brings up the stream of mentions for the user
Brings up the compose tweet dialog, pre-populated with the specified message
Brings up search results for the specified query
Brings up the user's mailbox

Install Tracking and Context Resumption

SPARQ optimized links can be enhanced with advanced tracking of app installations. Integrating with this system provides a variety of services, including the following:

  • Analytics on link visits and app invocations driven through the app store
  • Continuity of Experience—allowing the app to pick up the deep-linked URI of the originally-visited link after installation of the app
Consult the Tracking Invocations section of the SPARQ API documentation for details on the steps needed to integrate your mobile app.