Deep Linking in TWAs: Setting Up Android App Links

One of the primary benefits of packaging a Progressive Web App into a native Android app wrapper is the ability to integrate deeply with the mobile operating system. A key integration point is deep linking. When a user clicks a link pointing to your website, you want that link to open directly inside your installed Android app rather than inside a standard web browser.

In the Android ecosystem, there are two main types of deep links: standard deep links and Android App Links. Standard deep links use custom URI schemes, but they often trigger a system chooser dialog, asking the user which browser or app they want to use. Android App Links, introduced in Android 6.0, resolve this friction by allowing your app to associate itself directly with your domain. When verified, clicking a link to your domain launches your Trusted Web Activity instantly, bypasses the chooser dialog, and delivers a premium, native-feeling user experience.

Understanding Deep Links vs Android App Links

To successfully implement routing in your app, it is important to understand the technical distinction between standard deep links and verified Android App Links. The table below highlights the differences in behavior, verification requirements, and fallback options.

For a Trusted Web Activity, Android App Links are the preferred integration path. Because your TWA represents a direct conversion of your web portal, your app URLs are already fully functional web pages. Implementing Android App Links ensures that your native app and your website share a unified, interoperable routing system.

Configuring Intent Filters in the Android Manifest

To register your TWA as a handler for your domain URLs, you must declare intent filters inside your application AndroidManifest.xml. These filters tell the Android operating system which schemes, hosts, and path patterns your application is capable of handling.

The intent filter must be placed inside the activity declaration that manages your Trusted Web Activity. A standard configuration includes setting the action to view, category to default and browsable, and configuring the data tag to handle secure HTTPS requests.

For example, the data configuration must specify the host and the scheme explicitly. You must configure the intent filter to listen for https schemes and define your exact domain name. You can also specify path patterns if you only want certain subdirectories of your web application to open inside the native app wrapper. However, in most cases, developers map the entire host so that any link pointing to the platform is handled by the installed app.

Verifying Ownership with Digital Asset Links

Declaring intent filters in your manifest is only the first half of the equation. To prevent malicious applications from hijacking traffic intended for legitimate domains, Android requires verification. This is where Digital Asset Links come into play.

You must publish a JSON verification file at a specific path on your web server: https://yourdomain.com/.well-known/assetlinks.json. This file establishes a bilateral trust relationship between your website and your Android application package. The file contains relation statements that declare your application is allowed to handle target URLs on behalf of the domain.

The assetlinks.json file must contain the package name of your Android application and the SHA-256 fingerprint of your signing certificate. It is critical to use the correct certificate fingerprint. If you use Google Play App Signing, you must use the SHA-256 fingerprint provided by the Google Play Console, rather than your local upload key fingerprint, as Google signs the final distributed APK with their own certificate. If the fingerprints do not match, the system will silently fail to verify your app links, and URLs will continue to open in the standard mobile browser instead of your TWA.

Testing and Troubleshooting App Links

Verifying App Links can be challenging because Android handles verification asynchronously upon application installation. If verification fails, there is no explicit error message shown on the mobile UI. To diagnose issues, you must use the Android Debug Bridge (ADB) via your command line.

You can force Android to run the verification process immediately and output the results to your development console. By executing the specific package manager command for domain verification, you can inspect the state of your declared domains. The output will indicate whether the status is verified, set to ask, or denied.

Common reasons for verification failure include:

• Incorrect SHA-256 Fingerprint: Ensure you are using the fingerprint of the actual signing key (such as the Google Play App Signing Key) rather than your local debug or upload key.
• HTTPS Configurations: The assetlinks.json file must be served over a secure HTTPS connection with a valid SSL certificate. Self-signed certificates will fail verification.
• Content-Type Headers: Your web server must serve the assetlinks.json file with the application/json content-type header. Serving it as plain text can prevent the Android operating system from parsing it correctly.
• Redirects: Ensure that the URL path to your assetlinks file does not redirect. The verification system expects a direct 200 OK response when querying the file.

Optimising the In-App Navigation Experience

Once Android App Links are verified and fully operational, clicking any shared link, email notification link, or external message containing your domain will open the TWA seamlessly. To make the most of this capability, ensure your web application routing engine handles path routing dynamically.

When your TWA is launched via an App Link, the operating system passes the target URL directly to the launch intent. Your TWA wrapper reads this URL and passes it directly to the browser instance, loading the precise subpage the user clicked. Your PWA must be built using client-side routing (such as React Router or modern framework routing) that parses the path on initial load and renders the correct view instantly without forcing the user to navigate from the home screen manually.