I welcome you to the first installment of the deep links crash course series, where we’ll show a bit of context on what is a link, then we’ll go over each type of deep link, and, at the end, we’ll discuss some security notes. A summarized version is also available in video form. Otherwise, let’s get started!

Introduction

The deep links ecosystem is filled with lots of information and use cases. Nevertheless, you might be interested in just the basics of deep links, like “What can you do with them?”, “What is a deep link?”, “What is a link?”, “Who are deep links for?”.

Let’s answer these questions starting with the most important one: “Who are deep links for?” Users.

And they have one goal in mind: to get to the content they want to see. Your app needs to satisfy this goal.

If they don’t get to your content in an easy way, they might stop using your app and move on to another one. Therefore, it’s critical to provide a good user experience when working with deep links.

We will be working with an app called Droidfood to showcase examples of deep links code. Droidfood is an app where the user can order their favorite food.

The non-divergence URI

There are multiple definitions of what is a link. For our purposes we will focus on this one:

“A link is a sequence of characters that will take us someplace”

Let’s see a living example of this definition:

Let’s discuss each part piece by piece:

• “https:” Is the scheme and helps us identify which type of link we are working with. In this case, the link is part of the secure hypertext transfer protocol
• “droidfood.example.com” is the authority and host name which contains a hierarchical form from the top level domain to the subdomains.
• “/locations” is the path that will help us locate a particular resource from the authority

Now that we know what links are, we can answer another question: “What is a deep link?” We can use our previous definition to help answer this question; we just need to add a bit more:

“A link is a sequence of characters that will take us someplace, which could be an Android app or any other resource on the Internet”

Any link into an Android app can be a deep link. It all depends on how the link is configured, which we will discuss in the following sections.

From URIs to Android App Links

In this section, we will be going over each type of deep link from a URI perspective and taking into account each URI component we previously mentioned to answer our last question: “What can you do with them?”

There are different types of deep links. As the following picture shows, each deep link type is a special case of another type:

Deep Links

Taken from the URI perspective, deep links have the least specific rules on how to create them. Here are two different deep link examples from the Droidfood app. The first will take us to a list of the locations, the second will take us to the restaurants that are near us:

https://droidfood.example.com/locations

droidfood://near-me

Here are the URI rules for creating a deep link:

• The scheme can be a well-defined one — such as https, mail, or sms — or we can use a custom one.
• The authority should be a domain structure so that it’s easier to identify.
• The path can be used to pass parameters to your logic and send users to a particular screen in your app.

Using a custom scheme for creating deep links can help users reach your in-app content effectively. However, deep links don’t have a centralized registry of ownership, so any app can sign up to handle a particular deep link. This causes the disambiguation dialog to appear when the user follows a deep link that multiple apps have defined:

Before Android 12 the disambiguation dialog may appear under the following circumstances:

• Your app defines an Android App Link (we will review it later in this post), but that link was unable to be verified.
• After the user selected the “always open” option from the dialog, it may appear again after an app update which causes a permission to be revoked all

There are various schemes that can help with various built-in intents. They can cover various features within Android some of them include (but not limited to):

• “tel” for phone
• “file” for music or video
• “mailto” for Email
• “geo” for mapsMaps
• “sms” for messaging
• … and many more

One of the most common ways to use deep links is to help navigate the user to a particular activity. In our droidfood app, we have 3 activities:

• LocationsActivity
• DeliveryOptionsActivity
• AboutUsActivity

For now, we only care about taking them to the location’s activity. Therefore, our deep link examples will work just fine (taking into account the possible appearance of the disambiguation dialog, which we already mentioned)

When the user clicks on this link:

droidfood://locations

It will be taken into that activity.

Navigation is a very interesting topic and very useful with deep links, we will discuss it in a future blog post of this series. There is also the MAD video series that shows how to do this with Jetpack Navigation.

Web Links

These links inherit all of the characteristics of deep links, and they follow the same syntax rules but in a more specific way.

In summary, web links look like any other link out there on the Internet. Let’s take a look at one for our droidfood app:

https://droidfood.example.com/about-us

This link will take you to the page where it will tell the user more about us like our mission and story.

In order for the system to handle a web link correctly, you must configure it in a specific way:

• The scheme component must be either http or https.
• The authority component is your web host name and needs to be reachable on the Internet.
• The path is optional and mostly depends on how you’ve configured your website.

Starting from Android 12, all web links open in the browser unless an association between your website and the Android app has been configured. This association is the basis for Android App Links. More details about this change can be found in the Android 12 behavior changes documentation.

This table explains that, starting from Android 12, all web links that aren’t associated with your Android app are opened in a browser.

If there is an association between the web link and the Android app and the app is installed, the link will open in the app. If the app is not installed the link will open on the browser.

On previous Android versions, the disambiguation dialog may appear if there are multiple handlers for the web link, like other browsers or apps:

Android App Links

This is the most specialized type of deep link and has the most specialized rules. Since we already know what web links are, Android App Links are basically web links that involve more configuration steps. This process will verify the ownership of the link. Every time a user follows an Android App Link that has been verified, it will always open in your app, and the disambiguation dialog will not appear.

https://droidfood.example.com/locations

This link will open in our app and list our restaurant locations.

The scheme component as with web links must have http or https

The authority & path are similar to those you provided for web links. They reflect your web host name and must be reachable from the Internet.

As mentioned above, the extra configuration requires the following details:

• An “autoVerify” attribute set to true in your app’s intent filter, which lets your app to be the default handler for a given type of link
• Declare an AssociationThere needs to be an association between a page on your website and your Android app. This takes the form of a JSON file called “assetlinks.json” and it must be accessible publicly through the “.well-known” directory under your website’s root directory.

Also, it is worth noting that you have to make sure your website responds to the link so that users without your app still end up on the correct page.

Let’s explore a couple of situations where Android App Links make sense:

Link sharing

Let’s say you want to invite a friend to lunch and they are curious about the menu. You just share the link, and since they have the app installed they can see what’s on the menu directly in the app.

This is a pretty common scenario for all Android App Links and offers the best user experience. Just remember if your friend does not have the app installed, your website must respond to that link so they can see the restaurant menu from your website.

Path parameter parsing

You want to share a coupon code for 15% percent off your dinner delivery menu. (That’s a good deal!) In this case, you can share the link with your customers so that your app automatically applies the coupon at checkout.

This link might take the following form

https://droidfood.example.com/delivery?code=15off

We mentioned that the query is optional, and here is a very good use case for including a query. Every time a user clicks on the link, they’ll be redirected to your app. In your app’s logic, you can receive the code parameter for validation.

A few security notes

Android App Link verification

Before Android 12, if you have a link which failed verification, the disambiguation dialog appears for all of your links. This means that other apps can add those links to their manifest, leaving your users open for a potential risk.

For example let’s assume https://droidfood.example.com is not verified. Then the Malicious app could add this link to the manifest and the user will see both apps in the disambiguation dialog:

To mitigate the risk it is recommended that all web links should be verified, because if there’s even one link which failed the verification, the disambiguation dialog will appear for all of them. Please follow this link for more information on how to verify your links

Sensitive information

Be careful when generating links with sensitive information. If you need to include sensitive information in URLs, consider using server-generated opaque tokens that can be invalidated when they are no longer needed.

https://droidfood.example.com/login?token=tDsZE6rk1cwFPVDTCqkGbA

Link interception

Users can change the link handling behavior on their device, which means links can be intercepted by other apps or browsers. People can also copy and paste links anywhere, so make sure you design your system with this in mind. Links that you want to open in your Android app might still open in a browser or a different app chosen by the user.

Actions with side effects

Links are a great way to help users complete an action, but you need to make sure users are not tricked into performing an unexpected action. For example, you can create a link to “Add a Tip” that opens the tipping screen in your app, but the app should not submit the payment until the user confirms the tip in the app.

What’s next

I hope that this introduction helps you understand the world of deep links and make informed decisions on how to include them in your app.

Now, we’ll take a closer look at implementation. We’ll do that in a second installment of this series: Deep links from zero to hero.

After the implementation we will look at our third installment which discussed common problems with deep links and how to fix them.

Deep links will help you with user conversion which we will go over in part four of our video series.

• Part 1: What can you do with deep links?
• Part 2: Deep links from Zero to Hero
• Part 3: Overcoming Challenges Creating Android App Links
• Part 4: Deep links for your business

Happy Linking!