Publishing Web Apps with Trusted Web Activities

This article provides a comprehensive guide on how Trusted Web Activities (TWAs) enable developers to package and publish full-screen Chromium web experiences directly to the Google Play Store. It covers the fundamental architecture of TWAs, how they differ from standard WebViews, the cryptographic verification required to remove the browser UI, and the specific tools used to bundle a Progressive Web App (PWA) into a store-ready Android package.

What is a Trusted Web Activity?

A Trusted Web Activity is an Android feature that allows a mobile app to open a full-screen browser tab within the application itself. Instead of building a native user interface using Java or Kotlin, the Android app acts as a thin wrapper that launches a specific URL.

Unlike a traditional Android WebView—which uses a stripped-down, isolated rendering engine—a TWA runs directly on the user's installed Chromium-based browser (typically Google Chrome). This means the web app has full access to modern web APIs, hardware acceleration, and the browser's shared storage. If a user is already logged into your website on Chrome, they will automatically be logged into your TWA app because they share the same cookies and cache.

The Custom Tabs Protocol

Under the hood, TWAs are built on top of the Chrome Custom Tabs protocol. Custom Tabs allow developers to launch a fast, integrated browser window over their app. TWAs take this a step further by completely hiding the browser's URL bar, navigation buttons, and menus. Because the web content takes up 100% of the screen, the user experiences the website as if it were a standard native Android application.

Hiding the URL bar presents a security risk, as a malicious developer could theoretically wrap a banking website inside an app and trick users. To prevent this, Chromium enforces a strict verification process before it agrees to hide the browser UI. Developers must prove they control both the Android app and the website being displayed.

This is achieved using Digital Asset Links:

  1. App-side declaration: The developer adds a metadata tag inside the Android app’s AndroidManifest.xml file, pointing to the website's domain.
  2. Web-side declaration: The developer uploads a file named assetlinks.json to the .well-known directory of their website (e.g., https://example.com/.well-known/assetlinks.json). This file contains the Android app's package name and the SHA-256 fingerprint of the cryptographic key used to sign the app.

When the user launches the app, Chrome checks the website's assetlinks.json file in the background. If the digital signatures match, Chrome trusts the app and renders the website in full-screen mode. If the check fails, Chrome falls back to displaying a standard Custom Tab with a visible URL bar.

Packaging the Web App for Google Play

The Google Play Store does not accept URLs; it requires compiled Android App Bundles (.aab) or APKs. However, developers do not need to write native Android code or even install Android Studio to create a TWA. Google and the open-source community provide automated tools that generate the wrapper code for you:

  • Bubblewrap: An official command-line interface (CLI) tool developed by Google. You provide Bubblewrap with the URL to your web app's manifest.json file. It automatically downloads your app icons, configures the Digital Asset Links, and compiles a signed Android App Bundle ready for the Play Store.
  • PWABuilder: A web-based graphical tool maintained by Microsoft that utilizes Bubblewrap in the background. Developers simply enter their website URL, click a few buttons to customize the wrapper settings, and download the compiled package files directly from their browser.

Requirements for Play Store Approval

Before wrapping a web experience in a TWA and submitting it to the Google Play Store, the web app must meet specific quality criteria:

  • Progressive Web App (PWA) Compliance: The website must have a valid Web App Manifest and a registered Service Worker to handle offline states. Because native apps do not show a "No Internet Dino" screen, your Service Worker must provide a custom offline user interface when connectivity drops.
  • Performance Standards: The web app must achieve a performance score of at least 80 in Google Lighthouse.
  • Play Store Policies: The web app must adhere to all standard Google Play Store developer policies, including those regarding content, privacy, and payments. If the TWA sells digital goods, it must integrate the Digital Goods API to process payments through Google Play Billing.

Once these requirements are met and the .aab file is generated via Bubblewrap or PWABuilder, the developer can upload the file to the Google Play Console just like any other native Android application. Updates to the app's UI or functionality can then be deployed instantly by simply updating the website, bypassing the need to submit new app versions to the Play Store.