This blog post was originally published in 2018. It has been updated to reflect changes in Android App Links.
Opening an installed app from a browser is known as “deep linking,” and with this guide you’ll learn how to deep link into your Android app from the mobile web. We’ll focus exclusively on how to trigger an app open from a website page, rather than from the click of a link inside other apps.
Android is, by far, one of the most fragmented platforms that developers have ever had to manage, due to Google’s decision to force device manufacturers to be responsible for porting the OS, which requires backwards compatibility and support of a multitude of devices. In this ecosystem, we, the app developers, are left to pick up the pieces. Deep linking on Android is unfortunately no different— over the years, we’ve seen a plethora of technical requirements that must be used depending on the circumstance and context of the user.
Note that Branch will implement all of this complexity for you, host the deep links, and even give you robust analytics behind clicks, app opens, and down funnel events. You can play around with Branch links for free by signing up here. We highly recommend using our tools instead of trying to rebuild them from scratch, since building deep links is incredibly complicated.
Overview of Android App Links
Android App Links are Android’s solution to take users to specific in-app content. They allow your users to bypass the disambiguation dialogue where they select if they want to see content on the mobile web or in the app, such as in the following image:
App Links use HTTP and HTTPS URLs associated with your website domain, and allow a specific app to be the default owner of a given type of link. This ensures that no other app can use your links for deep linking. Note that with App Links, users who do not have your app installed will be taken to your mobile website. Therefore, for the best user experience, configure your mobile website to handle your App Link to prevent users from viewing a 404 page.
Steps to Create Android App Links:
1. Create intent filters for incoming links, and define values in your manifest
To link to your app content, create an intent filter with the following elements and attribute values to be used in your Activity tag within your manifest:
- <action>: To specify the VIEW intent action so that the intent filter can be reached from Google Search or other web link clicks.
- <data> : The <data> tag must include the android:scheme attribute. The data tags represent a URI format that resolves to the activity.
- BROWSABLE category: required in order for the intent filter to be accessible from a web browser. Without it, clicking a link in a browser cannot route users to your app.
- DEFAULT category: to allow your app to respond to implicit intents.
Here’s an example of an intent filter within a manifest for deep linking, using the URI “https://www.example.com/gizmos” :
<intent-filter
android:autoVerify="true"
android_label="@string/filter_view_http_gizmos">
<action android_name="android.intent.action.VIEW" />
<category android_name="android.intent.category.DEFAULT" />
<category android_name="android.intent.category.BROWSABLE" />
<!-- Accepts URIs that begin with "https://www.example.com/gizmos” -->
<data android_scheme="https"
android_host="www.example.com"
android_pathPrefix="/gizmos" />
<!-- note that the leading "/" is required for pathPrefix-->
Note that you can use http but then add the network configuration XML file with cleartextTrafficPermitted=true. More information here. Also, note that cleartext information transmitted is not encrypted and is not secure.
Adding intent filters with URIs for activity content to your app manifest allows Android to route any Intent that has matching URIs to your app.
2. Read data from incoming intents
Use data from your intent to determine the content to show your users. Call the getData() and getAction() methods to retrieve the data and action associated with the incoming intent.
Here’s a code snippet showing how to retrieve data from an intent in Java:
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
Intent intent = getIntent();
String action = intent.getAction();
Uri data = intent.getData();
}
Or in Kotlin:
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.main)
val intent: Intent = intent
val action: String? = intent.action
val data: Uri? = intent.data
}
3. Verify ownership of your app and website
As of January 2023, the Google Play Store is requiring all new apps and updates to target at minimum Android 12, or API level 31. Starting with Android 12, you must verify ownership of both your app and your website in order to deep link your users to your app content. Follow these steps:
Request automatic app link verification in your manifest.
This will ask the Android system to verify that your app belongs to the URL domain used in your intent filters.
Setting android_autoVerify=”true” declares your app to be the default handler for a type of link for any one of the web URL intent filters in your app manifest that include the android.intent.action.VIEW intent action and android.intent.category.BROWSABLE intent category.
Declare the relationship between your website and your intent filters
To indicate the Android apps associated with your website and app URL intents, start by publishing a Digital Asset Links JSON file at https://domain.name/.well-known/assetlinks.json.
You’ll need the following information to publish the Digital Asset Links JSON file:
- namespace: This value is “android_app”
- package_name: The application ID declared in the app’s build.gradle file.
- sha256_cert_fingerprints: The SHA256 fingerprints of your app’s signing certificate. You can use the following command to generate the fingerprint via the Java keytool:
$ keytool -list -v -keystore my-release-key.keystore
Here’s an example:
https://branchster.app.link/.well-known/assetlinks.json
Make sure that your assetlinks.json file is:
- served with content-type application/json.
- accessible over an HTTPS connection, regardless of whether your app’s intent filters declare HTTPS as the data scheme.
- accessible without any redirects (no 301 or 302 redirects) and accessible by bots (your robots.txt must allow crawling /.well-known/assetlinks.json).
- published on each domain if your app links supports multiple host domains
Finally, confirm that the Digital Asset Links JSON file is properly hosted and defined by using the Digital Asset Links API.
4. Test URL Intents
After verifying the websites associated with your app and ensuring 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://domain.name:optional_port"
The adb tool will launch an implicit intent android.intent.action.VIEW with the category BROWSABLE and data being your website URL you’ve configured.
You can also review a list of the links handled by all your apps with the following command:
adb shell dumpsys package domain-preferred-apps
You’ll see in the output all the linking behaviors for apps. Ensure that your app is set to always open on a link click.
“Package: your.app.package
Domains: your.domain.com
Status: always : 20000000c
The hexadecimal value is the Android system’s record for app linking behavior.
And you’re done! That being said, deep linking on Android is incredibly complicated, and there are edge cases everywhere. You’ll think everything is going well until you come across unique edge cases and broken links. That’s why you should use a tool like Branch — to save you from that nightmare and ensure that your links work everywhere. Contact us to discover how you can implement deep links that transform your user experience, reduce churn, and increase ROI.