App Links and custom URL schemes both let you open a mobile app from a web link, but they work very differently under the hood. This guide explains the key differences, when to use each, and how to implement them step by step. You’ll learn how App Links use HTTPS verification for security, while custom schemes are simpler but less secure and more prone to conflicts.
What You’ll Need
- An Android app project (Android Studio recommended)
- Access to your app’s manifest file (AndroidManifest.xml)
- A web domain you control (for App Links only)
- Basic knowledge of intent filters and URL structure
Step-by-Step
1. Understand the Core Difference
Custom URL schemes are like a private phone number—only your app knows it. When a link like myapp://open is clicked, Android asks which app can handle that scheme. App Links, on the other hand, are like a verified business address—they use HTTPS URLs (e.g., https://mywebsite.com/open) and require verification that your app owns that domain. This makes App Links more secure and less likely to be hijacked.
2. Implement a Custom URL Scheme
- Open your
AndroidManifest.xmlfile. - Find the
<activity>that should handle the link. - Add an
<intent-filter>with theVIEWaction andBROWSABLEcategory. - Add a
<data>element withandroid:scheme="myapp"(choose a unique scheme). - Optionally add a
android:host(e.g.,open) to make itmyapp://open. - Save and rebuild your app.
Example manifest snippet:
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="myapp" android:host="open" />
</intent-filter>
</activity>
3. Test the Custom Scheme
- Install the app on a device or emulator.
- Open a browser and type
myapp://openin the address bar. - Press Enter. You should see a dialog asking which app to open it with (if multiple handle it).
- Select your app and confirm it opens.
4. Implement App Links
- First, you need a domain you control (e.g.,
example.com). - In your manifest, add an intent filter similar to the custom scheme but with
android:scheme="https"andandroid:host="example.com". - Add the
android:autoVerify="true"attribute to the intent filter. - Create a file named
assetlinks.jsonon your web server athttps://example.com/.well-known/assetlinks.json. - The file must contain your app’s package name and SHA-256 certificate fingerprint (get it from Play Console or
keytool). - Upload the file and make sure it’s publicly accessible.
- Rebuild and install your app.
Example assetlinks.json:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.myapp",
"sha256_cert_fingerprints": ["AA:BB:CC:..."]
}
}]
5. Test App Links
- Open a browser on your device and go to
https://example.com/open. - If verification succeeded, your app should open directly without a disambiguation dialog.
- To test the verification, use the Digital Asset Links API:
https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls
Common Mistakes
- Using a generic scheme like
apporopen—these are often taken by other apps, causing conflicts. - Forgetting the BROWSABLE category—without it, the link won’t work from a browser.
- Not verifying your App Links—if the assetlinks.json is missing or incorrect, Android will treat the link as a custom scheme and show a chooser.
- Using HTTP instead of HTTPS for App Links—Android requires HTTPS for verification.
- Mixing up host and path—
hostis the domain,pathPrefixorpathis the specific part after the domain.
Tips
- Always use a unique scheme like
myappname://to avoid collisions. - For App Links, use the same domain for all links to simplify verification.
- Test on a real device, not just an emulator, to ensure the browser handles the link correctly.
- Use Android Studio’s App Links Assistant (Tools > App Links Assistant) to generate the assetlinks.json and add the intent filter automatically.
- If you support both, make the custom scheme a fallback for older Android versions (pre-6.0) that don’t support App Links.
Troubleshooting
App doesn’t open when clicking a link: First, check that the link is correctly formatted. For custom schemes, ensure the scheme is exactly as in the manifest. For App Links, verify the assetlinks.json is accessible and correctly formatted. Use the Digital Asset Links API to check.
Chooser dialog appears for App Links: This means verification failed. Common causes: wrong SHA-256 fingerprint, package name mismatch, or the assetlinks.json is not served over HTTPS. Double-check these.
Link opens in browser instead of app: For custom schemes, the browser may not support them (some do, some don’t). For App Links, the app might not be installed, or the link doesn’t match the intent filter’s path. Also, ensure the app is set as default for that domain in Android settings.
Scheme works only after app is opened once: This is a known Android behavior—the system may need to register the scheme after first launch. Force-stop the app and try again.
App Links work in Chrome but not in other browsers: Some browsers handle App Links differently. Test in multiple browsers and consider using the App Links Assistant to ensure proper configuration.
Frequently Asked Questions
Q: Can I use both custom schemes and App Links for the same URL?
A: Yes, you can have multiple intent filters in the same activity. However, it’s better to use App Links as the primary and custom scheme as a fallback for older devices.
Q: Do App Links work on iOS?
A: No, App Links are Android-specific. iOS uses Universal Links, which are similar but require a different configuration (apple-app-site-association file).
Q: Is it possible to open a specific screen with a deep link?
A: Yes, you can add path segments or query parameters to the URL and parse them in your activity to navigate to the right screen.
Q: What happens if two apps declare the same custom scheme?
A: Android will show a chooser dialog asking the user which app to open. This is why unique schemes are important.
Q: Do App Links require a specific Android version?
A: App Links were introduced in Android 6.0 (API 23). On older versions, they behave like custom schemes (showing a chooser).
Q: Can I use a subdomain for App Links?
A: Yes, but you must verify that exact subdomain. For example, links.example.com requires its own assetlinks.json file.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- MacBook Charger Not Working? Fix It Now
- Fix Windows Cannot Be Installed to This Disk
- Zoom on iPhone & iPad: Host or Join a Meeting
- Fix iPhone SE 4 Unable to Activate: Step-by-Step
- Keep Important Emails From Getting Buried in iPhone Mail Categories
- How to Clear RAM on iPhone: Speed It Up