How to Make QR Codes Open Your Installed Android TWA Directly

Physical QR codes are widely deployed in the physical world for restaurant menus, event ticketing, check-ins, and direct asset tracking. For SaaS founders and developers running a Progressive Web App (PWA) packaged inside an Android Trusted Web Activity (TWA), scanning a QR code should open the application directly. If the user has your app installed, triggering Chrome to open a standard web tab introduces unnecessary friction.

The Core Mechanism: Android App Links

To make a physical QR code open directly inside an installed TWA, you must implement Android App Links. While standard deep links (using custom schemes like myapp://) can open apps, they often trigger a system prompt asking the user to choose between the browser and your app. This choice disrupts the user flow.

Android App Links resolve this by establishing a cryptographic association between your web domain and your native app wrapper. When a user scans a QR code containing an HTTPS URL that matches your verified domain, the Android operating system bypasses the selection dialogue and opens the link directly inside the TWA container. If the app is not installed, the OS falls back gracefully to opening the URL in the default mobile browser.

Steps to Configure App Links for QR Code Launching

Achieving direct launches from QR codes requires configuring three critical components: the physical QR code payload, the Digital Asset Links configuration, and your Android Manifest intent filters.

1. Format the QR Code URL

Your physical QR codes must encode standard HTTPS URLs, not custom schemes. This ensures that users who do not have your app installed can still view your content via their mobile browser. For example, configure your QR code to point to:

https://example.com/check-in?table=42

2. Publish the Digital Asset Links File

To prove to the Android OS that you own the domain encoded in the QR code, you must host a JSON file at your domain's root. This file must be served over HTTPS with the correct content type and live at this precise path:

/.well-known/assetlinks.json

The JSON structure defines the relationship by matching your website domain with your Android application's package name and its signing certificate fingerprint:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.twa",
    "sha256_cert_fingerprints": ["XX:XX:XX..."]
  }
}]

3. Declare Intent Filters in the Android Manifest

Your TWA native wrapper must declare that it is ready to handle incoming URL intents for your specific domain. This is managed inside the AndroidManifest.xml configuration. The intent filter tells the operating system that your app is an eligible handler for your domain's links:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="example.com" />
</intent-filter>

The autoVerify attribute is critical. It instructs the OS to verify the association against the hosted assetlinks.json file immediately upon app installation. If the validation passes, all future clicks or scans targeting your domain will route straight to your TWA.

Preserving QR Code Query Parameters

When a user scans a QR code containing dynamic parameters, such as tracking tags or table identifiers, you must ensure your TWA successfully ingests these values. By default, a TWA launches using its configured Start URL. If a user scans a deep link, the Android system passes the full scanned URL into the TWA launch intent.

Your service worker and frontend Javascript can read these parameters directly from the window location on launch. This allows you to route the user to the correct sub-page or load context-specific data instantly.

Testing and Validating QR Code Routing

Before printing physical stickers or marketing displays, you must thoroughly verify your App Link configuration. Android includes debugging tools to check if your domain verification succeeded during installation.

Connect your test device via USB and use the following ADB command to check the domain verification status of your package:

adb shell pm get-app-links com.example.twa

If the verification state shows as approved, print a test QR code and scan it using the default Android camera app. The system should open your TWA instantly with no address bar and no intermediary browser popups. If it launches Chrome, check that your server is serving the assetlinks.json file with the exact content-type of application/json and that no redirects are blocking access to the path.