# Trusted Web Activity (TWA): PWAs in the Play Store

> What a Trusted Web Activity is, how it differs from a WebAPK, how Digital Asset Links verification works, and when to use TWA vs other install paths.

**In one line:** A Trusted Web Activity (TWA) is a full-screen Chrome Custom Tab that
passes a cryptographic origin verification check (Digital Asset Links), letting you ship
a PWA through the Google Play Store as a real Android app without an address bar.

## What a TWA is

A TWA is an Android activity (`com.google.androidbrowserhelper.trusted.TwaLauncher`)
that opens a URL in a full-screen Chrome Custom Tab. The critical difference from an
ordinary Custom Tab or WebView is **Digital Asset Links (DAL) verification**:

1. Your website hosts a JSON file at `/.well-known/assetlinks.json` that declares the
   SHA-256 fingerprint of your Android signing certificate.
2. Chrome verifies the fingerprint at launch. If it matches, Chrome shows the content
   with no address bar — the user sees a native-feeling app.
3. If verification fails, Chrome falls back to a normal Custom Tab **with** an address
   bar, which is the safe, graceful degradation path.

This is fundamentally different from a [WebAPK](/reference/installation/webapk):
a WebAPK is generated by Chrome at install time from the device without Play Store
involvement; a TWA is an Android app you build, sign, and submit to the Play Store.

## TWA vs WebAPK: when to use each

| | TWA | WebAPK (Chrome install) |
|---|---|---|
| Distribution channel | Google Play Store | Chrome browser install prompt |
| Requires Android app project | Yes (Kotlin/Java or Bubblewrap) | No |
| Digital Asset Links required | Yes | No |
| Address bar when verification fails | Shows address bar (graceful fallback) | N/A |
| Play billing / Play integrity | Accessible via postMessage bridge | Not accessible |
| Update mechanism | Play Store APK update | Manifest re-mint (~24 h) |
| Suitable for | Play Store presence, monetization, enterprise MDM | Quick "add to home screen" install |

## Setting up a TWA

### 1. Create the assetlinks.json

```json
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.myapp",
    "sha256_cert_fingerprints": [
      "AB:CD:EF:..."
    ]
  }
}]
```

Host this at `https://yourdomain.com/.well-known/assetlinks.json` with a
`Content-Type: application/json` header. The file must be reachable **without**
redirects; otherwise verification silently fails and the address bar appears.

### 2. Build the Android wrapper

The recommended path is **Bubblewrap CLI** (`@bubblewrap/cli`), an open-source tool
from Google that generates an Android Studio project pre-configured for TWA:

```bash
npm i -g @bubblewrap/cli
bubblewrap init --manifest https://yourdomain.com/manifest.json
bubblewrap build
```

Bubblewrap reads your web app manifest and generates the Android project. You supply the
signing key; Bubblewrap produces a signed APK and AAB ready for Play Store submission.

### 3. Pass Play Store review

TWAs are reviewed against Play's standard policies. Your PWA's web content is accessible
via URL, so Play may apply additional scrutiny. Common requirements: a real privacy
policy URL, working offline capability, and content that does not violate Play policies.

## Digital Asset Links verification detail

- Chrome fetches `assetlinks.json` at TWA launch (with a short network timeout).
- The fingerprint is compared to the APK's signing certificate.
- Verification results are **cached** for up to 5 minutes; a bad cache entry can delay
  the fix on a re-deploy.
- You can test verification with Android's Asset Links API tool or with:
  ```
  adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com com.example.myapp
  ```

## iOS

TWA is an Android-only technology. On iOS, Chrome for iOS exists but does not support
TWA. PWA distribution on iOS goes through Safari's "Add to Home Screen" mechanism;
there is no equivalent App Store path using web standards alone (a native iOS wrapper
using WKWebView is a separate approach outside the PWA/TWA model).

## Desktop

TWA is Android-only. ChromeOS supports TWA as well (since ChromeOS is Android-based),
allowing Play Store PWA apps to run on Chromebooks. Desktop Windows, macOS, and Linux
do not have a TWA equivalent; the analogous desktop path is a direct Chrome install
that uses a WebAPK-style isolated window.

## Play billing integration

TWAs can access Google Play billing through the
[Digital Goods API](https://developer.chrome.com/docs/android/trusted-web-activity/play-billing),
a Chrome-specific extension that exposes Play's payment infrastructure to web content
running inside a verified TWA. This is not available to ordinary browser PWAs.

## Compatibility

For distribution and browser support figures, see [/compatibility/](/compatibility/)
and [/ecosystem/distribution/](/ecosystem/distribution/).

## Practical checklist

- [ ] `assetlinks.json` hosted at `/.well-known/assetlinks.json`, no redirect, correct content-type.
- [ ] SHA-256 fingerprint of **release** signing certificate in the file (not debug).
- [ ] Bubblewrap (or equivalent) used to generate the Android project.
- [ ] `build.gradle` `applicationId` matches `package_name` in `assetlinks.json`.
- [ ] TWA verified with `adb` or Asset Links checker before Play submission.
- [ ] Privacy policy URL live and linked in the Play listing.
- [ ] Graceful address-bar fallback tested (temporarily break the fingerprint to confirm Chrome degrades cleanly).