Migrate Your Android TWA to a New Domain

Migrating a Progressive Web App (PWA) to a new domain is a common task for growing digital businesses. Whether you are rebranding, switching to a more professional top-level domain, or consolidating multiple web assets, a web-based migration is relatively straightforward using HTTP redirects. However, when that PWA is wrapped inside an Android app using a Trusted Web Activity (TWA), a domain migration introduces complex native challenges.

Because a TWA relies on a cryptographically secure handshake known as Digital Asset Links, changing the web address of your application requires careful preparation. If you configure the transition incorrectly, users of your installed Android app may suddenly see an visible browser URL bar, encounter certificate errors, or find themselves locked out of their accounts. This guide outlines the steps required to migrate your active Android TWA to a new domain without disrupting your user base.

The Dual-Domain Challenge in Android Apps

Unlike a standard web browser that allows users to navigate freely across different origins, a TWA is designed to merge the web and native spaces seamlessly. This is achieved by proving ownership of both the web origin and the Android application package. The verification mechanism requires the Android app to declare its target web origin, while the web server serves a verification file at a specific path.

When you change your PWA domain, you disrupt this association. During the migration phase, you will have two classes of users: those running the older version of your app targeting the legacy domain, and those running the updated version targeting the new domain. To ensure a smooth transition, your system must support both web origins simultaneously during the migration period. Failing to do so will cause the legacy app to strip its full-screen native appearance and display a browser URL address bar to users who have not yet updated their app.

Step 1: Deploying Digital Asset Links on Both Origins

The first and most critical rule of a TWA domain migration is that both the legacy domain and the new domain must actively serve the identical Digital Asset Links verification file. This file must be accessible via HTTPS at the exact path: /.well-known/assetlinks.json.

The Android operating system inspects this file when launching the application. If your old app is still installed on a user device, it will query the old domain. If that old domain no longer responds with a valid verification file, the application will drop out of Trusted Web Activity mode. Therefore, you must keep the old domain active and serving this file even after you have launched your new domain.

The file contents must declare your Android package name and the SHA-256 fingerprint of your app signing key. Below is an example of the structure that must reside on both servers:

[ { "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.twa", "sha256_cert_fingerprints": ["AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90"] } } ]

Step 2: Implementing Smart Web Redirects

Once both domains can verify your Android app, you must set up server-side redirects to guide web users and internal app traffic from the old domain to the new one. Most developers use a permanent HTTP 301 redirect for this purpose. However, you must establish strict redirect exemptions to prevent the Android operating system from failing its security validation.

Critical Redirect Exceptions

The Android system validation engine does not always follow HTTP redirects when fetching the assetlinks.json file. If a request to the old domain for /.well-known/assetlinks.json returns an HTTP 301 or 302 pointing to the new domain, the validation may fail on certain versions of Android Chrome. This will instantly restore the browser URL bar in legacy apps.

To prevent this, you must configure your legacy server to exclude the /.well-known/ directory from your global redirect rules. The legacy server must return a direct HTTP 200 OK status code with the correct raw JSON payload for all Digital Asset Links requests.

Step 3: Compiling and Versioning Your Updated App

With both web domains properly configured, you must build a new version of your Android application. This requires editing your TWA configuration to update the target launch URL and the fallback URL parameters.

First, update the launch URL in your build properties. If your previous build targeted https://example.com/, update this property to https://newexample.com/. Ensure that any custom query parameters used for tracking are preserved.

Second, increment your version code and version name in your build configuration. For example, if your current version code is 12, increment it to 13. Android devices will only accept updates that contain a higher version code than the currently installed binary.

Finally, compile your new signed APK and Android App Bundle (AAB) using your existing production keystore. You must use the exact same keystore and key alias as your previous releases, otherwise Google Play will reject the update due to a signature mismatch, and your existing users will not receive the update.

Step 4: Managing the Google Play Release Cycle

When deploying the new build to the Google Play Console, it is highly recommended to use a phased rollout strategy rather than releasing the update to 100% of your user base immediately. This allows you to monitor crash logs, user feedback, and server access logs to ensure that the transition is functioning correctly.

• Create a release in the Production track of your Google Play Console.
• Upload your new AAB file containing the updated launch URL.
• Select a phased rollout percentage, starting at 10% or 20% of your active install base.
• Monitor your web server logs on both the old and new domains. You should observe a gradual migration of user traffic from the old host to the new host as devices update the app.
• If any issues emerge with verification failures or layout issues, halt the rollout, address the web configurations, and then resume.
• Once validation is verified across your initial cohort, increase the rollout to 100%.

Step 5: Decommissioning the Legacy Domain

You cannot shut down your old domain immediately after publishing the new app. Because some users may have automatic updates disabled on their Android devices, or may not connect their devices to Wi-Fi regularly, a portion of your user base will remain on the legacy version of your app for weeks or even months.

Keep the legacy domain operational, with its SSL certificate active and the unredirected Digital Asset Links file intact, for at least six months following the migration. Check your Google Play Console analytics to monitor the percentage of active users still running legacy app versions. Once the active installations of the old version drop to a negligible percentage, you can safely decommission the old domain and complete your transition.