Platform in Installation
Trusted Web Activity
Published Updated
A Trusted Web Activity (TWA) is an Android activity that displays a web origin full-screen in the user’s browser (Chrome, from version 72) without a URL bar. Digital Asset Links must first verify that the APK’s signing key and the website belong to the same party. It is the route by which a PWA is listed on Google Play; Chrome 72 introduced it on Android, and the protocol is open to other browsers, though Chrome’s documentation records support only for Chrome itself.
How it works
Section titled “How it works”A TWA screen shows no web content bundled in the APK. Its launcher activity (com.google.androidbrowserhelper.trusted.LauncherActivity from the android-browser-helper library) binds through the Custom Tabs service to the user’s default browser when that browser supports TWA, otherwise to another installed browser that does, and asks it to open the app’s launch URL in trusted mode (Bubblewrap fills that URL from the manifest start_url). The browser renders the site with the user’s cookies, service workers, and storage.
The browser verifies trust when the app launches:
- The website publishes
/.well-known/assetlinks.jsonlisting the app’s package name and the SHA-256 fingerprint of its signing certificate under the relationdelegate_permission/common.handle_all_urls. - The APK declares the same origin in its
asset_statementsstring resource. - At launch the browser checks the assetlinks file (served as
application/json, reachable without redirects) and compares fingerprints. A match hides the URL bar; a mismatch, a missing file, or a redirect falls back to a normal Custom Tab with the URL bar visible, which is the designed fallback. The user sees no error;adb logcat | grep -e OriginVerifier -e digital_asset_linksshows why the check failed.
Because Play signs the uploaded app with its own key under Play App Signing, the fingerprint in assetlinks.json has to be the Play-managed signing key, not the local upload key; using the wrong signature is a common reason verification fails.
The alternative Android install paths differ in who builds the artefact and what it can reach:
| TWA | WebAPK (Chrome install) | Home Screen shortcut | |
|---|---|---|---|
| Distributed by | Google Play | Chrome at install time | Any browser |
| You build an Android project | Yes (Bubblewrap or Android Studio) | No | No |
| Digital Asset Links | Required | Not used | Not used |
| Play Billing | Yes, via the Digital Goods API | No | No |
| Updates | Web content: when you deploy the site; wrapper: a Play release | Manifest re-check by Chrome | None |
| Runs in | A browser that supports TWA, the user’s default first | Chrome | The installing browser |
Play Billing is reached from the web page through the Digital Goods API (window.getDigitalGoodsService('https://play.google.com/billing')) together with Payment Request. Chrome documents this for Trusted Web Activities only, and the Android app needs the billing extension; Google Play requires Play Billing for apps it publishes that sell digital goods.
Examples
Section titled “Examples”A TWA needs an assetlinks file on the site and an Android wrapper, which Bubblewrap can generate from the web manifest. A check in the page is optional and only matters for switching on Play-only features.
Publishing the Digital Asset Links statement
Section titled “Publishing the Digital Asset Links statement”The file lives at /.well-known/assetlinks.json on the origin. Each package name gets a statement, and its sha256_cert_fingerprints array lists the fingerprint of every signing key in use, debug and release alike.
[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.app", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] }}]The Play Console shows the correct fingerprint under Release › Setup › App signing › “App signing key certificate”; a statement built from keytool against the upload key passes locally and fails on Play-distributed builds.
Generating and building the wrapper with Bubblewrap
Section titled “Generating and building the wrapper with Bubblewrap”Bubblewrap reads the web app manifest and writes an Android project with the package name, icons, colours, and asset_statements filled in.
npm i -g @bubblewrap/clibubblewrap init --manifest https://example.com/manifest.webmanifestbubblewrap build # produces app-release-signed.apk and app-release-bundle.aabbubblewrap validate --url https://example.com/ # Lighthouse-based PWA checkThe generated project pins android-browser-helper; bubblewrap merge copies a changed web manifest into twa-manifest.json, and bubblewrap update regenerates the Android project from that file. Shipping the .aab to Play means the fingerprint in assetlinks.json must be Play’s signing key.
Detecting that the page is running inside the TWA
Section titled “Detecting that the page is running inside the TWA”Android’s default referrer for an activity is the android-app:// URI of the launching package, and Chrome passes it to the first page of a TWA launch. That makes it a workable signal for turning on Play-only features and hiding web install prompts, though no Chrome TWA page documents it, so treat it as a heuristic.
const fromTwa = document.referrer.startsWith('android-app://com.example.app/');
if (fromTwa && 'getDigitalGoodsService' in window) { enablePlayBilling(); // Digital Goods API is available here} else { enableWebCheckout(); // regular web payments everywhere else}installButton.hidden = fromTwa || matchMedia('(display-mode: standalone)').matches;Later navigations carry ordinary web referrers, so store the result (for example in sessionStorage) on the first page. display-mode: standalone matches inside a TWA too (unless Bubblewrap set fullscreen), and a WebAPK matches it as well, so the query cannot tell the two apart.
See also
Section titled “See also”- Trusted Web Activities overview (developer.chrome.com)
- Verify Android App Links (developer.android.com)
- Bubblewrap (github.com)
- Trusted Web Activity browser support
- WebAPK
- getInstalledRelatedApps()
- Distribution and store policy
Specifications
| Specification | Status |
|---|---|
| Trusted Web Activity availability | Vendor |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Android)# | Yes | 72 | medium | source | 123 |
- Per Chrome's documentation, Trusted Web Activity is available in Chrome on Android from version 72.
- No cross-browser compatibility dataset (BCD/caniuse) covers TWA; version verified from Chrome's own documentation.
- The same documentation notes other browsers may implement the same protocol, but does not itself document TWA support in any other browser.