How to Fix Deep Links Not Working in Flutter Apps Distributed via Firebase App Distribution

Introduction

Recently, while testing an app distributed via Firebase App Distribution in a test environment, I discovered that deep links were not working.

I managed to find a solution, but it took quite some time due to my lack of knowledge about deep links, especially Android app links. Therefore, I decided to document the process.

Preconditions

The following platform-specific settings described in the Flutter deep linking documentation are assumed to be complete:

• Android
  • Configuration in AndroidManifest.xml
  • Hosting <webdomain>/.well-known/assetlinks.json on your site with a valid response
• iOS
  • Enabling FlutterDeepLinkingEnabled
  • Adding the domain to Associated Domains in XCode’s Capabilities
  • Hosting <webdomain>/.well-known/apple-app-site-association on your site with a valid response

Deep linking

Navigate to routes when the app receives a new URL.

docs.flutter.dev

The Issue

On an actual device where the app distributed via App Distribution was installed, clicking a deep link for the configured domain resulted in the web page being opened instead of the app.

This issue occurred only on Android, while deep links worked normally on iOS.

Verification Steps

Deep Link Verification

First, connect the device with the app installed to a PC and use adb to verify if deep links are enabled. Specify the package name of the app and run the following command:

adb -s DEVICE_ID adb shell pm get-app-links PACKAGE_NAME

# DEVICE_ID is the ID output by `adb devices -l`. If multiple devices are connected, specify the device.

The following output was obtained:

com.sample.android:
  ID: xxxxx
  Signatures: [xxxxx]
  Domain verification state:
    mydomain.com: 1024

If the domain verification is successful, it should display verified next to the domain. In my case, it showed 1024, which seems to be a custom error code, indicating that domain verification failed.

However, I had correctly deployed the assetlinks.json file on my domain, and the response was valid.

Confirming SHA256 Signature Fingerprint

Since the site was functioning correctly, I suspected that the linkage between the domain and the app had failed. Comparing the SHA256 signature fingerprint from assetlinks.json with the one displayed in the earlier output, I noticed that they were different. I had followed the documentation and used the SHA256 displayed in the Play Console in my assetlinks.json, but it showed a different SHA256.

My app was built as an AAB, and I assumed that the app distributed via App Distribution was signed using the Play Console’s app signing. However, after some research, I discovered that the SHA256 in question was signed by Firebase App Distribution.

You can check the certificate for each release by hovering over the aab next to each release on the Android app page in App Distribution.

Register the SHA256 shown here in the assetlinks.json file.

The Play Console SHA256 is used for apps installed from the store, while the one from App Distribution is used for apps installed from there. As a result, my assetlinks.json ended up looking like this:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.sample.android",
      "sha256_cert_fingerprints": [
        "PlayConsole SHA256",
        "AppDistribution SHA256"
      ]
    }
  }
]

This allowed me to link the app distributed via App Distribution to the deep link domain.

Final Pitfall

After deploying the above assetlinks.json file to my site, I expected deep links to start working, but they still didn’t.

This turned out to be the most time-consuming part. Apparently, Android performs the domain verification for deep links when the app is installed. Since the verification had already failed, I needed to either reinstall the app or manually allow the domain from the app’s settings.

After reinstalling the app and clicking a deep link, the app opened successfully, and deep links started working properly.

Conclusion

The key points that caused me trouble were that apps distributed from App Distribution are signed by App Distribution, and that on Android, the domain verification for deep links is performed at the time of app installation. I hope this article saves someone else from wasting time on these issues.

References

Cómo verificar Android App Links  |  Android Developers

developer.android.com