Technical Guide to Android URI Schemes

This is part one of a four-part technical guide to deep linking on Android. The following posts will cover Chrome Intents, Android App Links, and Google Play Referrer.

Android is, by far, one of the most fragmented platforms that developers have ever had to deal with due to Google forcing device manufacturers to be responsible for porting the OS, requiring backward compatibility, and supporting a multitude of supported devices. This often results in a lengthy if-else statements to ensure that we use the most optimal method in the right context.

Android devices deep linking

Deep linking on Android is no different. Over the years, we’ve seen a plethora of technical requirements that must be used depending the circumstance and context of the user. Luckily, Branch ties all of these implementations together, creating a linking platform that works in every edge case. Branch links wrap and standardize this complexity so you don’t need to worry about it. We highly recommend using our tools instead of trying to rebuild them from scratch, since we give them all away for free.

This series will summarize all of the various deep linking mechanisms that we employ, and explain how they work and are implemented.

You can get started at or use the button below.

Android URI Scheme and Intent Filter

In Android 1.0, the Android URI scheme deep linking mechanism was created. It allows the developer to register their app for a URI (uniform resource identifier) in the operating system for a specific device once the app is installed. A URI can be any string without special characters, such as HTTP, pinterest, fb or myapp. Once registered, if you append ://  to the end (e.g. pinterest://) and click this link, the Pinterest app will open up. If the Pinterest app is not installed, you’ll see a ‘Page Not Found’ error.

Requirements for using Android URI Schemes
  • Register an Activity to respond to URI via an intent filter in the manifest.
  • App must be installed for use. If the app is not installed, it throws an error.
How to configure an Android URI Scheme

It is simple to configure your app for an Android URI scheme. To start, you need to pick an Activity within your app that you’d like to open when the URI scheme is triggered and register an intent filter for it. Add the following code within the <activity /> tag within your manifest that corresponds to the Activity you want to open.

You can change your_uri_scheme to the URI scheme that you’d like. Ideally, you want this to be unique. If it overlaps with another app’s URI scheme, the user will see an Android chooser when clicking on the link. You see this often when you have multiple browsers installed, as they all register for the HTTP URI.

Handling the deep link in the Android app

To handle the deep link in the app, you simply need to grab the intent data string in the Activity that was opened via the click. Below is an example:

Unfortunately, from here, you’ll need to do string parsing to read the values appended the URI scheme.

Practical use of Android URI Schemes

The URI method of deep linking is very restrictive and not recommended without significant modification as it will show an error message if your app is not installed. In order to use an Android URI scheme effectively by itself, you’ll need to build a couple tools on top of it to handle the critical edge cases such as when the app is not installed.

To ensure that clicking users still have a high-quality experience if the app is not installed, you must wrap the URI scheme in client-side Javascript that can execute in the browser. You would host this JS on your server and send the link to users. Below is an example:

The code will attempt to open up the app by setting an iFrame source to the URI scheme then fall back safely to the Google Play Store if the app fails to load.


Stay tuned for the upcoming posts in this series about Android deep linking.

Android is incredibly complicated and there are edge cases everywhere. You’ll think everything is going great until you get that one user complaining that his links aren’t working on Facebook while running Android 4.4.4. That’s why you should use a tool like Branch – to save you this nightmare and ensure that your links work everywhere. Interested in learning more? Be sure to request a Branch demo to get started.