How to Migrate from WebView Wrapper to TWA

For years, developers wanting to package web applications for the Google Play Store relied on WebView wrappers. Frameworks such as Apache Cordova or custom native wrappers allowed web developers to embed HTML, CSS, and JavaScript inside a native binary. However, as web standards evolved, the limitations of WebViews became apparent. Today, migrating from a WebView-based architecture to a Trusted Web Activity is the recommended pathway for delivering high-performance, compliant web apps on Android.

Why Migrate to a Trusted Web Activity?

The fundamental problem with WebViews is that they run in an isolated, stripped-down browser environment. They do not share cookies, storage, or cache with the user primary browser, and they frequently suffer from performance rendering bottlenecks. Furthermore, because WebViews are decoupled from the system browser, updating web APIs requires the user to update their system Android WebView component, which is not always guaranteed.

A Trusted Web Activity resolves these problems by running your web application directly inside the user installed system browser (typically Google Chrome). This architecture offers several technical advantages:

• Shared State: Cookies, local storage, and saved passwords are shared between the system browser and your native app, enabling instant sign-ins.
• Superior Performance: TWAs benefit from the full performance features of the latest Chromium engine, including advanced V8 JavaScript compilation and hardware-accelerated rendering.
• Consistent API Support: Modern Web APIs, such as Web Push, Web Share Target, and WebGPU, work immediately inside a TWA, whereas WebViews require complex custom Java bindings to support them.
• Reduced Binary Size: TWA app packages are highly lightweight because they do not need to bundle heavy rendering frameworks or native translation layers.

Comparing WebView and TWA Architectures

Before beginning the migration process, it is useful to compare how these two deployment models handle core application functions:

Step 1: Auditing Your WebView Plugins for Web API Alternatives

The first step in migrating is to identify and remove native wrapper plugins. WebView-based frameworks rely on native plugins to access hardware features. In a TWA environment, you replace these plugins with standard Web APIs. This reduces your codebase complexity by shifting logic entirely to standard browser APIs.

For instance, if your Cordova application uses the cordova-plugin-camera to capture photos, you should replace this with the standard HTML5 capture attribute or the MediaDevices API:

<input type="file" accept="image/*" capture="environment">

If you use plugins for local notifications, database access, or file system storage, look to modern web standards like the Web Notifications API, IndexedDB, and the Origin Private File System API respectively. This ensures your app is fully functional inside a browser tab as well as inside the Google Play wrapper.

Step 2: Preparing Your Web App Manifest

Unlike WebView wrappers, which rely on native configuration files like config.xml, a TWA configures its display properties directly from your web application Web App Manifest file. You must ensure your manifest.json is correctly configured before generating your TWA wrapper.

Ensure your manifest contains the mandatory fields for store presentation:

• short_name and name: Used by Android for the home screen icon and application list labels.
• start_url: The specific URL where the application should launch when opened.
• display: Set to standalone or fullscreen to hide the browser address bar.
• icons: Must include at least one icon of 192x192 pixels and one of 512x512 pixels in PNG format.

Step 3: Setting Up Digital Asset Links

The defining security feature of a Trusted Web Activity is the Digital Asset Link relationship. Under a standard WebView wrapper, any developer can load any URL inside their wrapper shell. TWAs prevent this hijacking by requiring cryptographic proof that the app developer owns the web domain being loaded.

To establish this trust, you must generate a Digital Asset Links JSON file (assetlinks.json) and host it on your web server at the exact path:

https://yourdomain.com/.well-known/assetlinks.json

This file contains your Android application package name and the SHA-256 fingerprint of your application signing keystore. Without this file, your application will launch with an active browser address bar, ruining the native experience. Converting your app with PWAtoApp ensures that your wrapper is built with the correct signature configurations to align perfectly with your asset links file.

Step 4: Preserving App Identity and User Data During Transition

If you are replacing an existing WebView wrapper app already published on the Google Play Store, you must handle the transition carefully to ensure that your existing users receive the update seamlessly without loss of identity.

To ensure Google Play recognizes the TWA as an update to your existing app, you must keep two values identical to your previous build:

1. The Package Name: The application ID (e.g., com.company.myapp) must match your existing application ID exactly.

2. The Signing Keystore: You must sign the new TWA AAB package with the identical keystore and alias that you used for your WebView build, or use Google Play App Signing with the original key. If you lose this key, you will not be able to upload your new TWA version to Google Play.

Step 5: Testing and Launching Your Migrated App

Once you have configured your manifest, removed legacy WebView plugins, verified your assetlinks.json file, and compiled your new signed AAB file, you are ready to test. Run the application on an Android emulator or a physical device.

Inspect your application using Chrome DevTools remote debugging to ensure that no browser navigation bars are visible and that your service worker is caching assets correctly for offline use. When you are satisfied that your TWA performs cleanly and handles system navigation flawlessly, upload your new AAB file to the Google Play Console to distribute the modern, high-performance update directly to your existing users.