“What can you do with deep links?”
Hello to all readers of the MyAdsMantra blog, where we’ll show a bit of context on what is a link, then we’ll go over each type of deep link. 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 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 hostname which contains a hierarchical form from the top-level domain (TLD) 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 to 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 permission to be revoked from 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 are not limited to):
- “tel” for phone
- “file” for music or video
- “mailto” for Email
- “geo” for Maps
- “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 hostname 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 Association There 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.
Deep links will help you with user conversion.
There are different types of deep links you can create in your Android app: standard deep links, web links, and Android App Links. Figure 1 shows the relationship among these types of links:
All forms of deep links are URIs that take users directly to specific content within your app.
- Web links are deep links that use the HTTP and HTTPS schemes.
- Android App Links are web links that are verified to belong to your app only.
Some example URIs:
- “example://droid.food.app” — URI with “example” custom scheme.
- “https://www.example.com/food” — URI with HTTPS scheme.
Implementing deep links
When a user clicks a link or an app programmatically invokes a URI intent, Android tries to find a handler application that can resolve the link.
To make sure that your app can be a handler, do the following 3 steps:
Step 1: Add intent filters for incoming links
Add intent filters to your Manifest file and drive users to the right place in your app, as shown in the following code snippet:
https://medium.com/media/5c5b93a527e0feab96cf5ddb3a1e7856Android intent filter
In this example, we added an intent filter that navigates users to the LocationsActivity.
Let’s explore the elements and attribute values of this intent:
Specifies the ACTION_VIEW intent action so that the intent filter can be reached from Google Search.
Include the BROWSABLE category. It is required in order for the intent filter to be accessible from a web browser. Without it, users can’t open your app from a deep link that appears in a browser.
Also include the DEFAULT category. This allows your app to respond to implicit intents. Without this, the activity can be started only if the intent specifies your app.
One or more <data> tags can be added, each of which represents a URI format that resolves the activity. The <data> tag must include the android:scheme attribute.
Once you’ve added one or more intent filters with URIs for activity content to your app Manifest file, Android is able to take any Intent that has matching URIs and routes that intent to your app at runtime. To learn more about defining intent filters and their attributes, check out Add intent filters for incoming links.
Step 2: Read data from incoming intents
Once the Android system starts your activity through an intent filter, you can use data provided by the Intent to determine what you need to render. Here’s a snippet that shows how to retrieve data from an Intent:
https://medium.com/media/cf68137e9903a49ed8044064e1e3090aRead data from an intent
You should also handle new Intents after the Activity has been created. If a user wants to open a link before the Activity is destroyed, you can get a new Intent with the Activity method onNewIntent().
https://medium.com/media/97bd54808b1a1e4826e6844f7f146edbHandling new intents
Step 3: Test your deep links
You can use the Android Debug Bridge to test deep linking resolve to the correct app activity. The general syntax for testing an intent filter URI with ADB is:
$ adb shell am start
-W -a android.intent.action.VIEW
-d <URI> <PACKAGE>
For example, the command below tries to view an app with a package = “food.example.com” that is associated with the URI = “example://food”:
$ adb shell am start
-W -a android.intent.action.VIEW
-d “example://food” food.example.com
The package name could be skipped for Implicit Intents but should be provided for Explicit intents. For more information about commands, and options check out Call activity manager (am) documentation.
The manifest declaration and intent handler you set above define the connection between your app and a deep link. Now let’s explore links that use HTTP and HTTPS schemes and how to make sure the system treats your app as the default handler.
Web links
Web links are deep links that use the HTTP and HTTPS schemes. They are implemented in the same way except that your intent filter includes the “http” or “https” scheme.
If you own a web link (own the domain and have a corresponding web page), then follow the instructions below for Android App Links.
If you don’t own a web link and your app’s main function might be to open links as a third party, then explain that to users and follow instructions on how to request the user to associate your app with a domain. Before you make this request for domain approval, provide some context for the user. For example, you might show them a screen that explains to the user why your app should be the default handler for a particular domain.
Android App Links
Android App Links are web links that are verified to belong to your app only. When a user clicks on a verified Android App Link, your installed app opens immediately. The disambiguation dialog will not appear.
If the app is not installed and the user didn’t set another app to be a default handler, then your link will be opened in a browser.
Android App Link Implementation
To set up Android App Links you need to do a few extra steps in addition to steps 1, 2, 3 above, and:
Step 4: Add “autoVerify” attribute to intent filters
To allow the system to verify that an Android App Link is associated with your app, add intent filters that match the following format:
https://medium.com/media/41e8c7cd66253a36cdbd803fc7f88725Add the autoVerify attribute for Android App Links
Step 5: Declare the association between your app and website
Declare the association between your website and your intent filters by hosting a Digital Asset Links JSON file at the following location:
https://food.example.com/.well-known/assetlinks.json
A Digital Asset Links JSON file must be published on your website to indicate the Android apps that are associated with the website and verify the app’s URL intents.
The following example assetlinks.json file grants link-opening rights to a droidfood.example.com Android app:
https://medium.com/media/8c804745e2478cd6625846d8bd241bc8assetlinks.json file for the Droidfood app
Verify that your signature is correct and matches the signature used to sign your app:
- You have the release signature in assetlinks.json. You can add a debug signature as well for testing.
- The signature should be in upper case.
- If you are using Play App Signing, make sure you’re using the signature that Google uses to sign each of your releases.
You can verify these details, including a complete JSON snippet, by following instructions about declaring website associations.
Step 6: Verify Android App Links
After you have confirmed the list of websites to associate with your app, and you have confirmed that the hosted JSON file is valid, install the app on your device. Wait at least 20 seconds for the asynchronous verification process to complete. Use the following command to check whether the system verified your app and set the correct link handling policies:
$ adb shell am start
-a android.intent.action.VIEW
-c android.intent.category.BROWSABLE
-d “https://food.example.com"
Note:
Starting in Android 12, you can manually invoke domain verification for an app that’s installed on a device. You can perform this process regardless of your app’s target SDK version.
In case something doesn’t work follow these instructions on how to fix common implementation errors for Android App Links. Also check out “Deeplinks video series crash course — Part 3: Challenges with DeepLinks”
Navigation Best Practices
Follow these best practices to improve the user’s experience:
- The deep link should take users directly to the content, without any prompts, interstitial pages, or logins. Make sure that users can see the app content even if they never previously opened the application. On subsequent interactions, such as when they open the app from the Android app launcher, it is OK to prompt users for steps they skipped to get to the deep link content.
- Follow the design guidance described in Navigation with Back and Up so that your app matches users’ expectations for backward navigation after they enter your app through a deep link.
Let’s look at the example of a deep link that opens the food details screen in Droidfood app.
In this example, the user follows a deep link that opens the “Cupcake details” screen. When the user taps back, the app shows the “Droidfood landing” screen instead of exiting. The app shows this screen because, from the “Droidfood landing” screen, the user can navigate back to “Cupcake details”. This navigation helps the user to know how to find the deep link content in the app in the future, without searching for the deep link again.
If you are using Android Jetpack’s Navigation component check out Create a deep link for a destination guide.
so far you’ve learned how to implement different types of deep links. We recommend using Android App Links, which helps to avoid disambiguation dialogs while seamlessly working when users don’t have your app installed. For more details about deep links, check out the guide Understanding the different types of links.
