sodcalculator

10 Tech How-To

App Links vs Custom URL Schemes: Key Differences

Guide 10-51087 · Updated · Step by step

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

  1. Open your AndroidManifest.xml file.
  2. Find the <activity> that should handle the link.
  3. Add an <intent-filter> with the VIEW action and BROWSABLE category.
  4. Add a <data> element with android:scheme="myapp" (choose a unique scheme).
  5. Optionally add a android:host (e.g., open) to make it myapp://open.
  6. 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

  1. Install the app on a device or emulator.
  2. Open a browser and type myapp://open in the address bar.
  3. Press Enter. You should see a dialog asking which app to open it with (if multiple handle it).
  4. Select your app and confirm it opens.

4. Implement App Links

  1. First, you need a domain you control (e.g., example.com).
  2. In your manifest, add an intent filter similar to the custom scheme but with android:scheme="https" and android:host="example.com".
  3. Add the android:autoVerify="true" attribute to the intent filter.
  4. Create a file named assetlinks.json on your web server at https://example.com/.well-known/assetlinks.json.
  5. The file must contain your app’s package name and SHA-256 certificate fingerprint (get it from Play Console or keytool).
  6. Upload the file and make sure it’s publicly accessible.
  7. 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

  1. Open a browser on your device and go to https://example.com/open.
  2. If verification succeeded, your app should open directly without a disambiguation dialog.
  3. 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 app or open—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—host is the domain, pathPrefix or path is 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

The whole Tech How-To bed →