TWA Versioning: When to Deploy to Web vs Google Play Store

The Two-Tier Architecture of a Trusted Web Activity

One of the greatest operational advantages of converting your Progressive Web App into an Android application via a Trusted Web Activity is the speed of iteration. Because a TWA is an Android container that renders your secure web origin inside a full-screen, system-managed browser session, your application architecture is split into two distinct tiers. The first tier is the native wrapper (the Android App Bundle or APK installed on the user device), and the second tier is the web application hosted on your web servers.

This architectural split often raises questions for developers regarding version control and deployment strategies. Developers frequently ask: "When I change my code, do I need to compile a new Android App Bundle and submit it to the Google Play Store, or will my users see the changes instantly?" Understanding this boundary is critical to maintaining a smooth deployment pipeline and avoiding unnecessary app store reviews.

Web Deployments: Instant Updates Without Store Review

The vast majority of updates you make to your application belong to the web tier. Because the TWA loads your web origin directly, any files served from your server are fetched in real-time or managed according to your Service Worker caching strategy. This means you do not need to build, sign, or upload a new Android App Bundle to Google Play for these changes.

The following changes can be deployed directly to your web server and will be visible to your native Android users almost instantly:

• User Interface and CSS: Layout modifications, color changes, responsive design updates, and font adjustments.
• Application Logic: JavaScript updates, new client-side features, bug fixes in your React, Vue, Angular, or vanilla JS code.
• Backend Integration: Modifying API endpoints, changing database queries, and integrating external web services.
• Service Worker Updates: Modifying offline assets, updating your runtime caching strategies, or changing web push notification payload handling.
• Content Updates: Publishing new articles, products, images, or media assets directly to your database or web server.

When deploying web updates, it is important to remember that your Service Worker controls resource caching. If your Service Worker is configured to cache assets aggressively, your TWA users might not see web updates immediately until the Service Worker detects a change in its service-worker.js file, installs the update, and prompts the user to refresh the app.

Native Deployments: When a Google Play Update is Mandatory

While web deployments cover most day-to-day changes, there are specific configurations that are hardcoded into the native Android application wrapper itself. These parameters are read by the Android operating system at runtime and cannot be changed by updating your web files. Changing these configurations requires you to compile a new Android App Bundle, increment your version codes, and submit a new release through the Google Play Console.

You must publish a native update to the Google Play Store when you make any of the following changes:

1. Modifying the Launch URL or Adding Allowed Origins

The native TWA wrapper contains a hardcoded starting URL. If you decide to change your launch path or migrate your application to an entirely new domain, you must update the Java/Kotlin configuration or the resource files in your wrapper and publish a new version. Furthermore, if your application navigates to a new subdomain or a secondary domain that needs to open inside the TWA container without displaying the browser address bar, this origin must be added to your native manifest configuration.

2. Changing App Icons and Splash Screens

While your PWA uses a web manifest to define icons for desktop and mobile home screens, the Android system requires native PNG resources for the launcher icon on the device home screen and app drawer. Similarly, the initial splash screen that displays while the browser engine is bootstraping is generated from native Android resources. Any modifications to these visual assets must be updated in your native app build.

3. Altering Native App Metadata

Metadata such as the application name displayed beneath the launcher icon, the Android package name, the supported screen orientations, or hardware permission declarations must be updated natively. For example, if you decide to declare support for a new hardware integration that requires native manifest permissions, this must be declared in the AndroidManifest.xml within your compiled bundle.

Comparing Web and Native Update Scenarios

The table below provides a clear map of common update scenarios and where those changes must be deployed.

Managing Version Codes and Version Names

When you determine that a native update is necessary, you must manage your Android versioning parameters correctly to ensure Google Play accepts your new bundle and updates your users seamlessly. Android uses two distinct version parameters:

Version Code (android:versionCode)

This is a positive integer used internally by the Android platform and Google Play to determine whether one version is more recent than another. Every time you upload a new AAB to the Play Store, the version code must be strictly greater than the previous version code. Even if your public-facing application version remains unchanged, this integer must increment by at least 1 for every upload.

Version Name (android:versionName)

This is a user-facing string that represents the version of your release. It can be formatted in any format you prefer, though semantic versioning (for example, 1.2.0) is the industry standard. This string has no programmatic influence on updates, but it is displayed to users in the Google Play Store and inside their Android application settings.

Structuring Your Release Workflow

To avoid friction, establish a clear release workflow for your TWA application. Minimise native configuration changes by planning your app metadata, icons, and domain structures carefully during your initial launch. This allows you to treat your Android application as a stable container, while focusing almost all your development efforts on your web deployment pipelines, giving you the power of web agility inside the mobile ecosystem.