A simple, annotation-based library for making deep link handling better on Android

By Christian Deonier and Felipe Lima

Deep links provide a way to link to specific content on either a website or an application. These links are indexable and searchable, and can provide users direct access to much more relevant information than a typical home page or screen. In the mobile context, the links are URIs that link to specific locations in the application.

At Airbnb, we use these deep links frequently to link to listings, reservations, or search queries. For example, a typical deep link to a listing may look something like this:


This deep link directly bypasses the home screen in the application and opens listing information for the Mushroom Dome cabin. Other deep links lead to other non-content screens like sign up screens or informational screens on how the application works.

Android supports deep links through declaration in the Manifest. You can add an intent filters which define a mapping between deep link schemas and Activities. Subsequently, any URI with the registered scheme, host, and path will open up that Activity in the app.

While convenient for simple deep link usage, this traditional method becomes burdensome for more complicated applications. For example, you could use the intent filter to specify the path pattern, but it’s somewhat limiting. You can’t easily indicate the parameters that you would expect in the URI that you are filtering for. For complex deep links, you are likely to have to write a parsing mechanism to extract out the parameters, or worse, have such similar code distributed amongst many Activities.

DeepLinkDispatch is designed to help developers handle deep links easily without having to write a lot of boilerplate code and allows you to supply more complicated parsing logic for deciding what to do with a deep link. You can simply annotate the Activity with a URI in a similar way to other libraries. Looking at the example deep link URI from above, you could annotate an activity like so, and declare an “id” parameter that you want the application to parse:

public class SomeActivity extends Activity {

After annotating a particular Activity with the deep link URI that the activity should handle, DeepLinkDispatch will route the deep link automatically and parse the parameters from the URI. You can then determine whether the intent was fired by a deep link and extract out the parameters declared in the annotation. Here’s an example:

if (getIntent().getBooleanExtra(DeepLink.IS_DEEP_LINK, false)) { 
Bundle parameters = getIntent().getExtras();
String someParameter = parameters.getString("id");

At its core, DeepLinkDispatch generates a simple Java class to act as a registry of what Activities are registered with which URIs, and what parameters should be extracted. DeepLinkDispatch also generates a shim Activity which tries to match any deep link with an entry in the registry– if it finds a match, it will extract the parameters and start the appropriate Activity with an Intent populated with the parameters.

Additionally, DeepLinkDispatch is intended to provide greater insight into deep link usage. Android by default does not give much insight into what deep links are being used nor what deep links are failing. DeepLinkDispatch provides callbacks in the Application class for any deep link call, either successful or unsuccessful, allowing developers to track and correct any problematic links firing at the application.

An example of such a callback would be:

public class SomeApp extends App implements DeepLinkCallback {
@Override public void onSuccess(String uri) {
// Handle or track a successful deep link here
  @Override public void onError(DeepLinkError error) {
// Handle or track and error here

In summary, use DeepLinkDispatch if you’d like an easy way to manage deep links. Declaring deep links and parameters are simple with annotations, and it will handle the more complex parsing and routing to your Activities without a lot of extra code on your part. DeepLinkDispatch also gives you greater insight into how your deep links are used by providing simple callbacks on deep link events for you to tie into.

For more information take a look at our Github page here:

Check out all of our open source projects over at and follow us on Twitter: @AirbnbEng + @AirbnbData

Originally published at on June 30, 2015.