Trusted Web Activity¶

A Trusted Web Activity (TWA) is an Android app whose only job is to open your Progressive Web App full screen in the user's browser, without any browser UI, after the browser has proved that the app and the website belong to the same developer. It's the mechanism behind almost every PWA listed on Google Play: the APK or App Bundle holds a launcher activity, icons, a splash screen and some configuration, while Chrome (or another supporting browser) renders the web content with its own engine, storage and service workers. Verification uses Digital Asset Links, so a missing or wrong fingerprint in /.well-known/assetlinks.json is the most common reason a "TWA" ships with a visible URL bar. This page covers the protocol, verification, the Bubblewrap and Android Browser Helper tooling, the delegated features (notifications, location, Play Billing), updates, debugging and how TWAs compare to WebAPKs and WebViews.

What a Trusted Web Activity actually is¶

Chrome shipped Trusted Web Activities in Chrome 72 for Android, in early 2019. The concept builds on two older pieces of Android infrastructure:

• Custom Tabs, introduced in Chrome 45, let an app open a URL in the user's browser inside the app's task, with a toolbar the app can color and customize. The page runs in the real browser, with the user's cookies, saved passwords and permissions.
• Digital Asset Links, Google's protocol for publicly declaring that a website and an app (or two websites) belong to the same principal. The same statement file powers Android App Links verification and Credential Manager sharing between an app and a site.

A TWA combines them: the app launches a Custom Tab with a flag that asks the browser to drop all browser UI, and the browser agrees only if Digital Asset Links show that the app's signing certificate and the site's origin are controlled by the same developer. The result looks like a native app (launcher icon, entry in Recents, no URL bar), but everything inside the window is the browser.

flowchart LR
    subgraph APK["Your Android app (APK / AAB)"]
        LA["LauncherActivity"]
        DS["DelegationService"]
        RES["asset_statements, icons, splash, colors"]
    end
    subgraph Browser["Chrome (TWA provider)"]
        CTS["CustomTabsService"]
        OV["Origin verifier"]
        TAB["Full-screen tab: renderer, storage, service workers"]
    end
    SITE["https://app.example.com/.well-known/assetlinks.json"]
    LA -- "bind + TWA launch intent" --> CTS
    CTS --> OV
    OV -- "fetch and match statements" --> SITE
    OV -- "verified: hide browser UI" --> TAB
    TAB -- "notifications, location, billing" --> DS

What that architecture means in practice:

The app has no direct access to web state. The Chrome documentation puts it bluntly: "The host app doesn't have direct access to web content in a Trusted Web Activity or any other kind of web state, like cookies and localStorage." Data flows from the app to the page through the launch URL (query parameters, share data, file handles) and, since Chrome 115, through a postMessage channel described later in this page.

Storage is shared with the browser, and Chrome tells the user¶

Because the TWA runs in the browser's profile, Chrome shows a one-time disclosure the first time a given app package launches a TWA. Chromium ships two variants of it: the older, shorter "Running in Chrome" and the newer "You'll see your site sign-in status, browsing data, and site data in Chrome", shown as a snackbar or as a notification depending on the Chrome version, device and configuration. Developers regularly mistake the "Running in Chrome" message for a verification failure; it isn't one. A failed verification shows a toolbar with the URL, not a one-time message. Chrome records per package whether the disclosure was seen and accepted, so it appears once per app, not once per launch.

When the user uninstalls the app or clears its data, Chrome can show a dialog titled "App name also has data in Chrome" with a "Keep Data" button and a path to the site settings, because clearing the APK's data doesn't touch the browser's storage for the origin. Bubblewrap-generated apps also add a "Site settings" launcher shortcut (enableSiteSettingsShortcut, on by default) that opens the browser's settings for the origin. For how browsers partition and evict that storage, see Storage Quotas & Persistence and Privacy & Storage Partitioning.

Timeline of the pieces you depend on¶

The Custom Tabs protocol underneath¶

You rarely touch the protocol directly (Android Browser Helper wraps it), but knowing it explains most TWA behavior, from browser selection to why the splash screen needs a FileProvider.

Discovering a TWA provider¶

A browser advertises Custom Tabs support by exporting a service that handles the intent action android.support.customtabs.action.CustomTabsService (CustomTabsService.ACTION_CUSTOM_TABS_CONNECTION). It advertises TWA support by adding the category androidx.browser.trusted.category.TrustedWebActivities (CustomTabsService.TRUSTED_WEB_ACTIVITY_CATEGORY) to that service's intent filter. Android Browser Helper's TwaProviderPicker queries the package manager for activities that handle an http VIEW intent (default-category matches first, then, on Android 6.0+, all matches), walks that list, which in practice usually starts with the user's default browser, and returns the first match in this priority:

1. The first browser whose Custom Tabs service carries the TWA category → launch mode TRUSTED_WEB_ACTIVITY. (Chrome 72 to 74 supported TWAs before the category existed, so the library special-cases them by version code.)
2. Otherwise, the first browser with any Custom Tabs service → CUSTOM_TAB.
3. Otherwise, any browser that handles http VIEW intents → BROWSER.

This ordering has a consequence you should plan for: if the user's default browser supports TWAs, your app typically opens in that browser, not necessarily in Chrome. On a phone whose default browser is Samsung Internet or Edge, the TWA runs there, with that browser's storage, cookies and feature set. If a feature you depend on (notification delegation, for example) isn't supported by every TWA browser, test on each, or pin a browser with the LAUNCHING_BROWSER metadata described in the Android Browser Helper section.

On Android 11 and later, package visibility rules hide other apps unless you declare what you need to query. Android Browser Helper's own manifest contributes a <queries> entry for VIEW intents on https URLs, which the manifest merger adds to your app. If you implement the protocol yourself, also declare the Custom Tabs service action:

<queries>
    <intent>
        <action android:name="android.support.customtabs.action.CustomTabsService" />
    </intent>
</queries>

Sessions, warm-up and the launch intent¶

The launch sequence Android Browser Helper runs for you looks like this:

sequenceDiagram
    participant User
    participant LA as LauncherActivity
    participant CT as Browser CustomTabsService
    participant OV as Browser origin verifier
    participant Site as assetlinks.json
    User->>LA: tap launcher icon
    LA->>LA: pick provider, show splash screen
    LA->>CT: bindService(ACTION_CUSTOM_TABS_CONNECTION)
    CT-->>LA: onCustomTabsServiceConnected(client)
    LA->>CT: warmup(), newSession(callback)
    LA->>CT: transfer splash image through FileProvider
    LA->>CT: launch TWA intent (session, URL, colors, display mode, splash params)
    CT->>OV: verify origin of the launch URL for the calling package
    OV->>Site: GET /.well-known/assetlinks.json
    Site-->>OV: statements
    alt statement matches package and certificate
        OV-->>User: full-screen content, splash fades out on first paint
    else no match
        OV-->>User: same content in a Custom Tab with URL bar
    end
    LA->>LA: finish() once the browser is launched

A few protocol details are worth knowing:

• The session identifies the caller. The browser learns the calling package from the Custom Tabs session. Verification binds three things: that package name, its signing certificate as reported by Android's package manager, and the origin of the URL being displayed.
• warmup() starts the browser process early. The Custom Tabs guide cites savings of up to 700 ms. Android Browser Helper calls it for you.
• The TWA intent is a Custom Tabs intent with extras. TrustedWebActivityIntentBuilder (in androidx.browser.trusted) builds it. Its public setters map almost one-to-one to Bubblewrap options: setToolbarColor, setNavigationBarColor, setNavigationBarDividerColor, setColorScheme, setColorSchemeParams, setDefaultColorSchemeParams, setAdditionalTrustedOrigins, setSplashScreenParams, setShareParams, setFileHandlingData, setDisplayMode, setDisplayOverrideList, setScreenOrientation, setOriginalLaunchUrl and setLaunchHandlerClientMode. The corresponding intent extras use the androidx.browser.trusted.extra. prefix (for example androidx.browser.trusted.extra.DISPLAY_MODE).
• Display modes are classes, not strings. TrustedWebActivityDisplayMode has DefaultMode, ImmersiveMode(isSticky, layoutInDisplayCutoutMode), MinimalUiMode, BrowserMode, TabbedMode and WindowControlsOverlayMode implementations; the browser decides which it supports.
• Relationship validation has two relations. CustomTabsService.RELATION_HANDLE_ALL_URLS (value 2) corresponds to the delegate_permission/common.handle_all_urls statement that TWAs rely on. RELATION_USE_AS_ORIGIN (value 1) corresponds to delegate_permission/common.use_as_origin, needed for the postMessage channel.

What "verified" means while the user navigates¶

Verification isn't a one-off launch check; the browser evaluates every top-level navigation:

• Navigations within the verified origin (or any origin you list in additionalTrustedOrigins and verified with its own assetlinks.json) stay full screen.
• A navigation to any other origin shows the Custom Tabs toolbar with the URL and an X button that returns the user to the app, so users always know when they have left your site. OAuth and payment redirects to third-party origins therefore show a toolbar briefly, which is expected.
• Subresources and iframes aren't checked; only the top-level document's origin matters.

Digital Asset Links: proving the app and site belong together¶

Verification needs statements in two places: the app says "I want to act for this site", and the site says "this app, signed with this certificate, may act for me". Getting either side wrong produces the dreaded URL bar.

flowchart TD
    A["TWA launch for https://app.example.com/"] --> B{"Browser supports TWA?"}
    B -- no --> F1["Android Browser Helper fallback: Custom Tab or WebView"]
    B -- yes --> C{"assetlinks.json fetched: HTTP 200, valid TLS, no redirect, JSON?"}
    C -- no --> F2["Custom Tab with URL bar"]
    C -- yes --> D{"Statement with handle_all_urls, this package_name and a matching sha256 fingerprint?"}
    D -- no --> F2
    D -- yes --> E["Full screen, no browser UI"]

The app side: asset_statements¶

The APK points at the site with a string resource referenced from <application> metadata. Bubblewrap generates both:

<application ...>
    <meta-data
        android:name="asset_statements"
        android:resource="@string/assetStatements" />
</application>

<resources>
    <string name="assetStatements">
        [{
            \"relation\": [\"delegate_permission/common.handle_all_urls\"],
            \"target\": {
                \"namespace\": \"web\",
                \"site\": \"https://app.example.com\"
            }
        }]
    </string>
</resources>

The site value is an origin: scheme and host, plus port only if it isn't the default. No path, no trailing slash needed. For every extra origin you list in additionalTrustedOrigins, add another statement with that origin.

The site side: /.well-known/assetlinks.json¶

The website publishes a JSON array of statements at exactly /.well-known/assetlinks.json on the origin being opened. Google's documentation is explicit that statement lists "in any other location, or with any other name, are not valid for this site."

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app.twa",
      "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",
        "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
      ]
    }
  }
]

The fingerprints above are placeholders; yours come from the keys described in the next section. The rules the Digital Asset Links documentation sets for serving the file:

Every origin needs its own file. app.example.com and www.example.com are different origins, and so are example.com and example.com:8443.

# Inside the server { } block for https://app.example.com
# Exact-match location: wins over SPA fallbacks and trailing-slash rewrites.
location = /.well-known/assetlinks.json {
    root /srv/www/app;                  # file lives at /srv/www/app/.well-known/assetlinks.json
    types { }                           # ignore mime.types for this location...
    default_type application/json;      # ...and force application/json
    add_header Cache-Control "public, max-age=3600";
}

import express from "express";

const router = express.Router();

// Fingerprints come from configuration so staging and production can differ.
// Fail at startup rather than serve an empty or broken statement list.
const { TWA_PACKAGE_ID, TWA_SHA256_FINGERPRINTS } = process.env;
if (!TWA_PACKAGE_ID || !TWA_SHA256_FINGERPRINTS) {
  throw new Error("TWA_PACKAGE_ID and TWA_SHA256_FINGERPRINTS must be set");
}
const statements = [
  {
    relation: ["delegate_permission/common.handle_all_urls"],
    target: {
      namespace: "android_app",
      package_name: TWA_PACKAGE_ID,
      sha256_cert_fingerprints: TWA_SHA256_FINGERPRINTS.split(",").map((f) =>
        f.trim().toUpperCase()
      ),
    },
  },
];
const body = JSON.stringify(statements);

// Register this before any SPA catch-all route or HTTPS redirect middleware.
router.get("/.well-known/assetlinks.json", (req, res) => {
  res.set("Content-Type", "application/json");
  res.set("Cache-Control", "public, max-age=3600");
  res.status(200).send(body);
});

export default router;

{
  "hosting": {
    "public": "dist",
    "ignore": ["firebase.json", "**/node_modules/**"],
    "headers": [
      {
        "source": "/.well-known/assetlinks.json",
        "headers": [{ "key": "Content-Type", "value": "application/json" }]
      }
    ],
    "rewrites": [{ "source": "**", "destination": "/index.html" }]
  }
}

Which SHA-256 fingerprints to list¶

Android verifies an app by its signing certificate, and the certificate that signs the APK on a user's device is often not the one on your laptop. List every certificate that can sign a build users or testers install:

The most frequent production bug is shipping an assetlinks.json that lists only the local key: sideloaded builds work, the Play Store build shows a URL bar. With Play App Signing, Google re-signs your app with the app signing key, so that key's fingerprint must be in the file. With Play's quantum-ready hybrid signing (a classical RSA-4096 key plus an ML-DSA-65 post-quantum key, verified by Android 17+ devices through APK Signature Scheme v3.2), Play uses a different classical key for newer devices than for older ones, so copy every SHA-256 fingerprint the Play app signing page shows. A fingerprint too many does no harm; a missing one breaks verification for a subset of devices, which is much harder to diagnose.

# From a keystore (Bubblewrap's default path and alias):
keytool -list -v -keystore ./android.keystore -alias android | grep "SHA256:"

# From a built APK or AAB (shows the certificate that actually signed it):
keytool -printcert -jarfile app-release-signed.apk | grep "SHA256:"

# From an APK with the Android SDK build tools (handles v2/v3 signature schemes):
apksigner verify --print-certs app-release-signed.apk | grep "SHA-256"

# From an app installed on a device (useful to inspect the Play-delivered build):
adb shell pm path com.example.app.twa          # prints package:/data/app/.../base.apk
adb pull /data/app/<path-from-above>/base.apk play-build.apk
apksigner verify --print-certs play-build.apk | grep "SHA-256"

apksigner prints fingerprints as lowercase hex without colons, while assetlinks.json uses uppercase, colon-separated pairs. Convert rather than retype them.

Bubblewrap can keep the list in twa-manifest.json and generate the file for you:

# Add the Play App Signing key (paste from Play Console) with a label:
bubblewrap fingerprint add "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C" --name="play-app-signing"

bubblewrap fingerprint list
bubblewrap fingerprint remove "<fingerprint>"

# Writes an assetlinks.json containing all stored fingerprints:
bubblewrap fingerprint generateAssetLinks --output=assetlinks.json

Verifying the statement list the way Google sees it¶

Google exposes the Digital Asset Links API, which fetches and parses your file with the same rules. Two endpoints are useful:

# Everything Google can parse from your site's statement list:
curl -s "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://app.example.com&relation=delegate_permission/common.handle_all_urls"

# A yes/no answer for one package and one certificate:
curl -s "https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https://app.example.com&relation=delegate_permission/common.handle_all_urls&target.android_app.package_name=com.example.app.twa&target.android_app.certificate.sha256_fingerprint=FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
# → { "linked": true, "maxAge": "3599.99s" }

The maxAge in the response (about an hour) shows that Google caches statement lists; after fixing the file, a stale negative result can persist for a while. The Digital Asset Links Statement List Generator and Tester wraps the same API in a form.

For CI, a script that checks the transport rules directly catches the problems the API reports only as "not linked":

// Usage: node scripts/check-assetlinks.mjs https://app.example.com com.example.app.twa FINGERPRINT [FINGERPRINT...]
// Exits non-zero when the statement list would fail Digital Asset Links verification.

const [origin, packageName, ...fingerprints] = process.argv.slice(2);
if (!origin || !packageName || fingerprints.length === 0) {
  console.error("usage: check-assetlinks.mjs <origin> <package> <sha256> [sha256...]");
  process.exit(2);
}

const RELATION = "delegate_permission/common.handle_all_urls";
const normalize = (fp) => fp.replace(/[^0-9a-f]/gi, "").toUpperCase();
const errors = [];

async function checkTransport() {
  const url = new URL("/.well-known/assetlinks.json", origin);
  // redirect: "manual" because Digital Asset Links does not follow redirects.
  const res = await fetch(url, { redirect: "manual" });
  if (res.status !== 200) {
    errors.push(`${url} returned HTTP ${res.status}; only 200 is accepted (redirects are not followed)`);
    return null;
  }
  const type = res.headers.get("content-type") || "";
  if (!type.toLowerCase().startsWith("application/json")) {
    errors.push(`Content-Type is "${type}", expected application/json`);
  }
  const text = await res.text();
  try {
    const json = JSON.parse(text);
    if (!Array.isArray(json)) errors.push("Top-level value must be a JSON array");
    return json;
  } catch (err) {
    errors.push(`Body is not valid JSON (${err.message}); first bytes: ${text.slice(0, 60)}`);
    return null;
  }
}

function checkStatements(statements) {
  const listed = new Set();
  for (const s of statements) {
    const relations = Array.isArray(s?.relation) ? s.relation : [];
    const t = s?.target;
    if (!relations.includes(RELATION)) continue;
    if (t?.namespace !== "android_app" || t?.package_name !== packageName) continue;
    for (const fp of t.sha256_cert_fingerprints ?? []) listed.add(normalize(fp));
  }
  if (listed.size === 0) {
    errors.push(`No ${RELATION} statement for package ${packageName}`);
    return;
  }
  for (const fp of fingerprints) {
    if (!listed.has(normalize(fp))) errors.push(`Fingerprint ${fp} is not listed for ${packageName}`);
  }
}

async function checkWithGoogle() {
  // Ask Google's Digital Asset Links API, which applies the production parsing rules.
  for (const fp of fingerprints) {
    const api = new URL("https://digitalassetlinks.googleapis.com/v1/assetlinks:check");
    api.searchParams.set("source.web.site", origin);
    api.searchParams.set("relation", RELATION);
    api.searchParams.set("target.android_app.package_name", packageName);
    api.searchParams.set("target.android_app.certificate.sha256_fingerprint", fp);
    const res = await fetch(api);
    const body = await res.json().catch(() => ({}));
    if (!res.ok || body.linked !== true) {
      errors.push(`Digital Asset Links API: not linked for ${fp} (HTTP ${res.status})`);
    }
  }
}

try {
  const statements = await checkTransport();
  if (statements && Array.isArray(statements)) checkStatements(statements);
  await checkWithGoogle();
} catch (err) {
  errors.push(`Network error: ${err.message}`);
}

if (errors.length) {
  for (const e of errors) console.error(`✗ ${e}`);
  process.exit(1);
}
console.log(`✓ ${origin} delegates handle_all_urls to ${packageName} for ${fingerprints.length} key(s)`);

One statement file, three consumers¶

The handle_all_urls relation is shared with Android App Links: Bubblewrap's generated manifest declares an https VIEW intent filter with android:autoVerify="true" for your host, so Android itself also verifies the app against the same file and, when verification succeeds, opens links to your site directly in the app instead of offering a chooser. On Android 12 and later you can inspect that system-level verification with adb shell pm get-app-links <package> (see Debugging). The browser's TWA verification and Android's App Links verification are separate checks against the same statements, so one can pass while the other is still pending. If you also share credentials between the app and the site, add delegate_permission/common.get_login_creds to the same statement's relation array. For link capture and launch behavior on the web side, see Protocol Handlers & Launch Handling.

Building a TWA with Bubblewrap¶

Bubblewrap is Google's command-line tool that generates, builds and signs a TWA Android project from a web app manifest. PWABuilder uses it under the hood for its Android package. The current release is 1.25.0 (published July 31, 2026), which raises targetSdkVersion and compileSdkVersion to 36 and moves the Play Billing module to 1.2.0.

Requirements¶

Install it globally without sudo: npm i -g @bubblewrap/cli. Check what you actually got with bubblewrap version before a release build. The 1.25.0 rollout showed why: for its first days the CLI couldn't be installed from npm because its @bubblewrap/[email protected] dependency hadn't been published (issue #1055), and until late August 2026 the ghcr.io/googlechromelabs/bubblewrap:1.25.0 image contained CLI 1.24.1 and generated targetSdkVersion 35 (issue #1056). Both are fixed. In CI, pin an exact CLI version and assert targetSdkVersion in the generated app/build.gradle, so a stale toolchain fails the build instead of failing Play's review.

Step 1: bubblewrap init¶

mkdir my-twa && cd my-twa
bubblewrap init --manifest=https://app.example.com/manifest.webmanifest

init downloads your web app manifest and asks you to confirm or change each derived value. The prompts, in order of the underlying strings, are: Domain, URL path, Application name, Short name, Application ID, Starting version code, Display mode, Orientation, Status bar color, Splash screen color, Icon URL, Maskable icon URL, Monochrome icon URL, Include app shortcuts?, Include support for Play Billing?, Request geolocation permission?, Key store location and Key name, followed by the keystore questions (names, organization, two-letter country, keystore and key passwords) if the key doesn't exist yet.

Flags change what init generates:

The Application ID defaults to your host reversed with .twa appended: app.example.com becomes com.example.app.twa. Choose it carefully: the package name is permanent on Google Play, and it's the package_name in assetlinks.json.

Step 2: understand twa-manifest.json¶

init writes twa-manifest.json, the single source of truth for the Android project. Bubblewrap regenerates the Android files from it on update, and warns that it "doesn't expect the generated Android project to be updated using external editors", so make changes here rather than in Gradle or XML files. A realistic, complete example:

{
  "packageId": "com.example.app.twa",
  "host": "app.example.com",
  "name": "Example Tasks",
  "launcherName": "Tasks",
  "display": "standalone",
  "displayOverride": [],
  "orientation": "default",
  "themeColor": "#1A73E8",
  "themeColorDark": "#0B1A2E",
  "navigationColor": "#FFFFFF",
  "navigationColorDark": "#000000",
  "navigationDividerColor": "#00000000",
  "navigationDividerColorDark": "#000000",
  "backgroundColor": "#FFFFFF",
  "enableNotifications": true,
  "startUrl": "/?source=twa",
  "iconUrl": "https://app.example.com/icons/icon-512.png",
  "maskableIconUrl": "https://app.example.com/icons/maskable-512.png",
  "monochromeIconUrl": "https://app.example.com/icons/monochrome-192.png",
  "splashScreenFadeOutDuration": 300,
  "signingKey": {
    "path": "./android.keystore",
    "alias": "android"
  },
  "appVersion": "7",
  "appVersionCode": 7,
  "shortcuts": [
    {
      "name": "New task",
      "shortName": "New",
      "url": "https://app.example.com/tasks/new",
      "chosenIconUrl": "https://app.example.com/icons/shortcut-new-96.png"
    }
  ],
  "generatorApp": "bubblewrap-cli",
  "webManifestUrl": "https://app.example.com/manifest.webmanifest",
  "fallbackType": "customtabs",
  "features": {
    "locationDelegation": { "enabled": false },
    "playBilling": { "enabled": true },
    "firstRunFlag": { "enabled": true, "queryParameterName": "first_run" }
  },
  "alphaDependencies": { "enabled": false },
  "enableSiteSettingsShortcut": true,
  "isChromeOSOnly": false,
  "isMetaQuest": false,
  "minSdkVersion": 23,
  "additionalTrustedOrigins": ["checkout.example.com"],
  "fingerprints": [
    { "name": "upload", "value": "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" },
    { "name": "play-app-signing", "value": "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C" }
  ],
  "shareTarget": {
    "action": "/share",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": { "title": "title", "text": "text", "url": "url", "files": [{ "name": "file", "accept": ["image/*"] }] }
  },
  "protocolHandlers": [
    { "protocol": "web+tasks", "url": "/open?link=%s" }
  ],
  "fileHandlers": [
    { "actionUrl": "https://app.example.com/import", "mimeTypes": ["text/csv"] }
  ],
  "launchHandlerClientMode": "focus-existing"
}

init writes shortcuts entries (name, shortName, url and the chosen icon URLs) and the other nested objects from your web manifest, so treat the example as illustrative and edit the file Bubblewrap generated for you. The fields, their defaults and what they turn into in the Android project:

Most of these mirror web app manifest members; the key difference is that in a TWA they're baked into the APK at build time. Changing theme_color in your web manifest doesn't recolor the status bar until you run bubblewrap merge (or edit twa-manifest.json), update and ship a new version. See App Identity & Updates for the equivalent rules for browser-installed PWAs.

Step 3: bubblewrap build¶

bubblewrap build
# → app-release-signed.apk     (for testing and sideloading)
# → app-release-bundle.aab     (upload this to Google Play)

build compares twa-manifest.json with the checksum stored in manifest-checksum.txt; if you edited the manifest since the last generation, it offers to run update first. It then compiles with Gradle, zip-aligns and signs the APK, and builds and signs the App Bundle. Options: --skipSigning (produces unsigned outputs for signing elsewhere), --signingKeyPath and --signingKeyAlias (override the manifest), --manifest (path to twa-manifest.json) and --skipPwaValidation. The last one is still documented, but the 1.25.0 build command no longer calls the PWA validator at all, so it has no effect. When build prompts for the keystore and key passwords, it requires at least six characters, the same minimum keytool enforces.

Step 4: install, test and publish¶

bubblewrap install                  # adb install of ./app-release-signed.apk on the connected device
bubblewrap install --verbose        # prints the adb commands it runs

adb logcat -v brief | grep -e TWAProviderPicker -e OriginVerifier -e digital_asset_links

Then upload app-release-bundle.aab to an internal testing track, copy the Play App Signing fingerprint(s) into assetlinks.json, and install the Play-delivered build to confirm it opens without a URL bar. Publishing to App Stores covers the store listing, policy and review side; the bubblewrap play commands (publish with --track, which defaults to the internal track, versionCheck, and the experimental retain) automate uploads with a Play service account.

Other Bubblewrap commands¶

Android Browser Helper in a hand-written project¶

Android Browser Helper is the library Bubblewrap's generated project depends on. It sits on top of androidx.browser and provides LauncherActivity, TwaLauncher, TwaProviderPicker, DelegationService, the splash screen strategy, the WebView fallback and the site-settings activity. Use it directly when you add a TWA to an existing native app, need Kotlin/Gradle conventions Bubblewrap doesn't generate, or want to launch the TWA from a native screen rather than from the launcher.

The artifacts are versioned separately:

Bubblewrap 1.25.0 still pins androidbrowserhelper 2.6.2 for stable builds and 2.7.0-alpha02 with alphaDependencies. To use a feature that arrived later (high-priority notifications, explicit browser targeting), raise the version in app/build.gradle after each bubblewrap update, or maintain the project by hand. The 2.7 line depends on androidx.browser 1.10.0 and, like billing 1.2.0, requires minSdk 23.

android {
    compileSdk 36
    defaultConfig {
        applicationId "com.example.app.twa"
        minSdk 23             // androidbrowserhelper 2.7.x and billing 1.2.0 declare minSdkVersion 23
        targetSdk 36          // Required by Google Play for new apps and updates from Aug 31, 2026
        versionCode 7
        versionName "7"
        // Values referenced from AndroidManifest.xml
        resValue "string", "launchUrl", "https://app.example.com/?source=twa"
        resValue "string", "hostName", "app.example.com"
        resValue "string", "providerAuthority", "com.example.app.twa.fileprovider"
    }
}

dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.7.3'
    implementation 'com.google.androidbrowserhelper:billing:1.2.0'   // only with Play Billing
}

The manifest configures everything declaratively; LauncherActivity reads the android.support.customtabs.trusted.* metadata at launch:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:manageSpaceActivity="com.google.androidbrowserhelper.trusted.ManageDataLauncherActivity"
        android:theme="@android:style/Theme.Translucent.NoTitleBar">

        <meta-data android:name="asset_statements" android:resource="@string/assetStatements" />

        <!-- Target of manageSpaceActivity above and of the "Site settings" launcher shortcut.
             Like any activity, it only works if it's declared here. -->
        <activity
            android:name="com.google.androidbrowserhelper.trusted.ManageDataLauncherActivity"
            android:exported="false"
            android:excludeFromRecents="true">
            <meta-data android:name="android.support.customtabs.trusted.MANAGE_SPACE_URL"
                android:value="@string/launchUrl" />
            <intent-filter>
                <action android:name="android.intent.action.APPLICATION_PREFERENCES" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </activity>

        <activity
            android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
            android:alwaysRetainTaskState="true"
            android:exported="true">

            <meta-data android:name="android.support.customtabs.trusted.DEFAULT_URL"
                android:value="@string/launchUrl" />
            <meta-data android:name="android.support.customtabs.trusted.STATUS_BAR_COLOR"
                android:resource="@color/colorPrimary" />
            <meta-data android:name="android.support.customtabs.trusted.NAVIGATION_BAR_COLOR"
                android:resource="@color/navigationColor" />
            <meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
                android:resource="@drawable/splash" />
            <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
                android:resource="@color/backgroundColor" />
            <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
                android:value="300" />
            <meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
                android:value="@string/providerAuthority" />
            <meta-data android:name="android.support.customtabs.trusted.FALLBACK_STRATEGY"
                android:value="customtabs" />
            <meta-data android:name="android.support.customtabs.trusted.SCREEN_ORIENTATION"
                android:value="portrait" />

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <!-- App Links: open https://app.example.com/* in the app, verified via assetlinks.json -->
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="@string/hostName" />
            </intent-filter>
        </activity>

        <activity android:name="com.google.androidbrowserhelper.trusted.FocusActivity" />
        <activity android:name="com.google.androidbrowserhelper.trusted.WebViewFallbackActivity"
            android:configChanges="orientation|screenSize" />
        <activity android:name="com.google.androidbrowserhelper.trusted.NotificationPermissionRequestActivity" />

        <!-- The splash image is handed to the browser through this provider. -->
        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="@string/providerAuthority"
            android:grantUriPermissions="true"
            android:exported="false">
            <meta-data android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/filepaths" />
        </provider>

        <!-- Receives notifications and extra commands (location, billing) from the browser. -->
        <service
            android:name=".DelegationService"
            android:exported="true">
            <meta-data android:name="android.support.customtabs.trusted.SMALL_ICON"
                android:resource="@drawable/ic_notification_icon" />
            <intent-filter>
                <action android:name="android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </service>
    </application>
</manifest>

<paths>
    <files-path path="twa_splash/" name="twa_splash" />
</paths>

The manifest's .DelegationService is a class in your own package. It can be a one-line subclass; Bubblewrap generates the same thing and injects the handlers for the features you enabled into onCreate():

package com.example.app.twa;

import com.google.androidbrowserhelper.playbilling.digitalgoods.DigitalGoodsRequestHandler;

public class DelegationService extends com.google.androidbrowserhelper.trusted.DelegationService {
    @Override
    public void onCreate() {
        super.onCreate();
        // The base class already registers the notification-permission handler.
        // Register one handler per delegated feature; only needed with the billing module.
        registerExtraCommandHandler(new DigitalGoodsRequestHandler(getApplicationContext()));
        // With the locationdelegation module, also:
        // registerExtraCommandHandler(new LocationDelegationExtraCommandHandler());
    }
}

onExtraCommand() offers each command to the registered handlers in order and returns the first result that reports success, so the order matters only if two handlers claim the same command name.

The complete list of LauncherActivity metadata keys in the current library:

(… stands for android.support.customtabs.trusted..)

Customizing launch behavior in code¶

Subclass LauncherActivity when the launch URL depends on runtime state. Overridable hooks include getLaunchingUrl(), getUrlForIntent(Intent), shouldLaunchImmediately() with launchTwa(), getFallbackStrategy(), getDisplayMode(), getProtocolHandlers(), getSplashImageScaleType() and getCustomTabsCallback().

package com.example.app.twa;

import android.net.Uri;

import androidx.annotation.NonNull;

import java.util.Map;

public class LauncherActivity extends com.google.androidbrowserhelper.trusted.LauncherActivity {

    private static final String PARAM_SOURCE = "source";
    private static final String PARAM_APP_VERSION = "app_version";

    /**
     * Adds query parameters so the web app knows it runs inside this TWA and which
     * APK version launched it. The page reads them once and stores them, because
     * later same-document navigations won't carry them.
     */
    @Override
    protected Uri getLaunchingUrl() {
        Uri uri = super.getLaunchingUrl();
        return uri.buildUpon()
                .appendQueryParameter(PARAM_SOURCE, "twa")
                .appendQueryParameter(PARAM_APP_VERSION, String.valueOf(BuildConfig.VERSION_CODE))
                .build();
    }

    /** Maps web+tasks://... links (declared as an intent filter) to an https URL. */
    @NonNull
    @Override
    protected Map<String, Uri> getProtocolHandlers() {
        return Map.of("web+tasks", Uri.parse("https://app.example.com/open?link=%s"));
    }
}

BuildConfig.VERSION_CODE requires buildFeatures { buildConfig true } on recent Android Gradle Plugin versions. Map.of needs API level 30 or core library desugaring; use a HashMap if you target older devices without desugaring. When you replace the library's activity with your own subclass, point the manifest's <activity android:name> at your class.

Two behaviors of LauncherActivity explain task-management quirks you may see:

• One task per app. LauncherActivity always relaunches itself with FLAG_ACTIVITY_NEW_TASK (clearing FLAG_ACTIVITY_NEW_DOCUMENT), so the TWA occupies a single entry in Recents. If a TWA is already running and the user taps the launcher icon, the new LauncherActivity finishes immediately instead of navigating the existing TWA, unless the intent carries a URL or share data.
• It finishes after launching. Since Android Browser Helper 2.7.0, LauncherActivity calls finish() as soon as the launch callback reports that the browser activity started. The 2.6.2 release that Bubblewrap pins by default leaves it in the back stack and finishes it in onRestart() when the user comes back to it. Either way, Back from the TWA returns the user to wherever they came from, not to an empty launcher activity.

To open a TWA from inside a native app screen, for example a "Help" button that opens your web help center full screen, use TwaLauncher directly:

private TwaLauncher twaLauncher;

private void openHelp() {
    twaLauncher = new TwaLauncher(this);
    twaLauncher.launch(Uri.parse("https://app.example.com/help"));
}

@Override
protected void onDestroy() {
    super.onDestroy();
    if (twaLauncher != null) twaLauncher.destroy(); // unbinds the Custom Tabs service
}

What happens when a TWA can't be shown¶

There are three different failure paths, handled by different components. Confusing them is common, because two of them look the same to the user.

Verification failure is a soft failure again¶

In June 2020 the Chromium blog announced that, starting in Chrome 86, Chrome would treat three conditions as native app crashes reported to Android vitals: an HTTP 404 or 5xx for a main document on a trusted origin, failure to return HTTP 200 for a main document while offline, and Digital Asset Links verification failure at launch. The mechanism was a Custom Tabs callback named quality_enforcement.crash; Android Browser Helper's default callback, QualityEnforcer, throws a RuntimeException when it receives it.

That enforcement didn't survive. Chromium removed its side with the commit "Remove TWA QualityEnforcer related code" in May 2023 (Chromium 115), and Chrome's related plan to require a working offline page for installability was put on hold "after listening to your feedback". Android Browser Helper still registers QualityEnforcer, so a browser that sent the message would still crash the app, but current Chrome doesn't send it. Current Chrome behavior on failed verification is the Custom Tab UI, as the Bubblewrap quick start describes.

The quality bar is still worth meeting: a 404 page or the browser's offline dinosaur inside a store-installed app is a bad review waiting to happen, and Google Play reviews the app like any other. Handle navigation failures in the service worker with an offline fallback page, as described in Offline UX & Fallbacks and Handling Fetch Events.

Choosing customtabs or webview¶

The WebView fallback keeps the app full screen on devices without a TWA-capable browser, but it's a different runtime: its own cookie jar and storage (the user isn't signed in), the system WebView's feature set (no service worker-based push notifications, no Web Share Target or Payment Request with Play Billing), and your app becomes responsible for WebView security settings. Bubblewrap adds the INTERNET permission when you pick webview. For most PWAs, the Custom Tabs fallback is the safer default: the user sees a URL bar, but everything works.

Detecting the TWA context in your web app¶

The page inside a TWA is an ordinary browser page. display-mode media queries reflect the mode the TWA was launched in, and for the default mode that's the same standalone value a browser-installed PWA reports, so they can't reliably distinguish a TWA from a WebAPK. Use signals the app controls:

• A query parameter on the start URL (startUrl: "/?source=twa" or the getLaunchingUrl() override above). A startUrl parameter is only on launches from the icon: App Links arrive with their own URL, and notification clicks are handled by your service worker, not by LauncherActivity. The getLaunchingUrl() override also tags App Link launches, because they pass through LauncherActivity. Persist the flag on first sight either way.
• document.referrer, which is android-app://<package-name>/ on the first navigation of a TWA launched by your app. It's a hint, not a proof: it disappears after the first navigation and can be spoofed by other apps.
• Bubblewrap's firstRunFlag feature, which appends a query parameter (named by queryParameterName) with true on the app's first launch and false afterwards.

// Detects whether this page runs inside our Trusted Web Activity and remembers it
// for the lifetime of the browsing session.
const STORAGE_KEY = "twa-context";
const TWA_PACKAGE = "com.example.app.twa";

function readStored() {
  try {
    return JSON.parse(sessionStorage.getItem(STORAGE_KEY));
  } catch {
    return null; // storage blocked or corrupt: fall back to live detection
  }
}

function store(value) {
  try {
    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(value));
  } catch {
    /* ignore: detection still works for this document */
  }
}

export function getTwaContext() {
  const stored = readStored();
  // A positive result sticks for the session; a negative one is re-evaluated, because
  // the first document of the session may have been opened without the parameter.
  if (stored?.isTwa) return stored;

  const params = new URLSearchParams(location.search);
  const fromParam = params.get("source") === "twa";
  const fromReferrer = document.referrer.startsWith(`android-app://${TWA_PACKAGE}`);

  const context = {
    isTwa: fromParam || fromReferrer,
    appVersion: Number(params.get("app_version")) || null,
    firstRun: params.get("first_run") === "true",
  };
  store(context);

  // Remove our launch parameters from the visible URL so they don't end up in
  // bookmarks, shares or analytics page paths.
  if (fromParam) {
    params.delete("source");
    params.delete("app_version");
    params.delete("first_run");
    const query = params.toString();
    history.replaceState(history.state, "", `${location.pathname}${query ? `?${query}` : ""}${location.hash}`);
  }
  return context;
}

Typical uses: hide an "Install app" banner (see Install Prompts & Custom UI), switch the checkout to Play Billing, tag analytics sessions (see Analytics for PWAs) and show a "please update the app" hint when appVersion is too old for a feature. Detecting Installed Apps covers getInstalledRelatedApps(), which lets a regular browser tab detect that your Play app is installed through the manifest's related_applications.

Splash screens¶

TWAs have their own splash screen mechanism, supported by Chrome since Chrome 75. It exists because, on a cold start, the browser process may take a noticeable time to start (Android Browser Helper's documentation mentions "seconds" on low-end devices), and a blank screen would look broken.

The handover works like this:

1. LauncherActivity (with a translucent theme) shows an ImageView with SPLASH_IMAGE_DRAWABLE centered on SPLASH_SCREEN_BACKGROUND_COLOR, and colors the system bars to match what the TWA will show.
2. If the chosen browser supports splash screens (TrustedWebUtils.areSplashScreensSupported() for version V1), the library writes the bitmap to files/twa_splash/ and grants the browser read access through the FileProvider.
3. The TWA intent carries the splash parameters: version, background color, scale type, optional transformation matrix and KEY_FADE_OUT_DURATION_MS.
4. The browser shows the same image on top of the loading page and removes it with the configured fade when the page has painted, so the user sees one continuous splash.

If the browser doesn't support splash screens, LauncherActivity degrades to a transparent trampoline. Bubblewrap generates the splash drawable from iconUrl and uses backgroundColor; hand-built projects should supply density-specific drawables or a vector drawable.

On Android 12 and later, the system also shows its own splash screen (the app icon on the window background) before any activity draws. With a translucent launcher theme, what users see depends on the theme and device, and some apps show the system splash followed by the TWA splash. Keep the two consistent: the same background color in the app theme and in backgroundColor, and an icon that reads well in both. Since Android Browser Helper 2.7.0 the splash view is laid out edge to edge, which matters because apps targeting API level 36 can't opt out of edge-to-edge on Android 16.

The web app's own splash and theming choices still matter after the handover: keep the first paint's background color equal to the splash color so the fade-out doesn't flash.

Display modes, orientation and system bars¶

The display value in twa-manifest.json becomes DISPLAY_MODE metadata:

displayOverride works like the web manifest's display_override: an ordered list the browser walks until it finds a mode it supports, including window-controls-overlay and tabbed for larger screens. It needs Android Browser Helper 2.7.0 or later to be passed to the browser.

Orientation reaches two places. The browser receives SCREEN_ORIENTATION and applies it to the TWA; separately, Bubblewrap's generated LauncherActivity calls setRequestedOrientation() for the splash screen, and only on API levels above 26, because setting an orientation on a translucent activity crashes on Android 8.0. Bubblewrap maps web orientation values to Android constants for the splash: portrait → SCREEN_ORIENTATION_USER_PORTRAIT, portrait-primary → PORTRAIT, portrait-secondary → REVERSE_PORTRAIT, landscape → LANDSCAPE, landscape-secondary → REVERSE_LANDSCAPE, and everything else (including landscape-primary, because of a landspace-primary typo in the current source) → UNSPECIFIED.

System bar colors come from the APK (themeColor, themeColorDark, navigationColor and their dark variants), selected by the system's light or dark setting. They're build-time values, so a theme switcher inside your web app can't change them; pick colors that work with both of your web themes.

Notification delegation¶

Without delegation, web push notifications from your origin would appear as Chrome notifications, grouped under Chrome in system settings. With delegation, the browser hands each notification to your APK, which posts it under your app's identity and icon. Delegation is on by default in Bubblewrap (enableNotifications: true).

How the delegation works¶

The browser finds a service in your APK that handles the action android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE and that's associated with the verified origin, binds to it, and calls it through the TrustedWebActivityService API. Android Browser Helper's DelegationService extends androidx's TrustedWebActivityService, which implements the notification calls, and adds a persistent token store and the extra-command dispatcher:

• onNotifyNotificationWithChannel(platformTag, platformId, notification, channelName) (inherited from androidx): posts the browser-built notification from your app, using the small icon from the service's SMALL_ICON metadata (Bubblewrap generates it from monochromeIconUrl, or from iconUrl if you have no monochrome icon).
• onAreNotificationsEnabled(channelName): reports whether the app, and that channel, may show notifications.
• onExtraCommand(...): the extension point that notification permission, location delegation and Play Billing use. You add handlers with registerExtraCommandHandler().

The Android 13+ permission flow¶

On Android 13 (API level 33) and later, apps need the POST_NOTIFICATIONS runtime permission, and an app targeting API level 33+ decides when the system dialog appears. Bubblewrap adds the permission to the manifest when notifications are enabled. When your page calls Notification.requestPermission() inside a TWA with delegation:

sequenceDiagram
    participant Page as Web page
    participant Chrome
    participant DS as DelegationService (your APK)
    participant Sys as Android
    Page->>Chrome: Notification.requestPermission()
    Chrome->>DS: extra command checkNotificationPermission(channelName)
    DS-->>Chrome: ALLOW, BLOCK or ASK
    alt ASK
        Chrome->>DS: getNotificationPermissionRequestPendingIntent
        DS-->>Chrome: PendingIntent for NotificationPermissionRequestActivity
        Chrome->>Sys: start activity, which requests POST_NOTIFICATIONS
        Sys-->>Chrome: user choice
    end
    Chrome-->>Page: "granted" or "denied"

The status is ALLOW when app notifications (and the channel) are enabled, BLOCK when they're disabled and the app has asked before, and ASK when they're disabled but the app has never requested the permission. The user's decision is the app's Android permission, visible and revocable in the app's system settings, rather than a Chrome site setting.

The web-side rules don't change: call Notification.requestPermission() from a user gesture, explain the value first, then subscribe with PushManager, exactly as on the web (Push Notifications, Notifications API, Permissions). An open issue in the Android Browser Helper repository (#563) reports cases where the page receives "granted" while the app's notification permission is still blocked, so check Notification.permission again after a push subscription and consider linking to the app's system notification settings from your UI if notifications never arrive.

Channels and high-priority notifications¶

On Android 8.0+, every notification belongs to a channel. The browser passes a channel name with each notification, and the channel is created on first use with an ID derived from that name (lowercased, spaces replaced by underscores, plus _channel_id) and IMPORTANCE_DEFAULT. Android Browser Helper 2.7.3 added an opt-in: add androidx.browser.trusted.USE_HIGH_PRI_NOTIFICATIONS metadata with the value true to your DelegationService declaration (the library reads it from the service's own metadata, not from <application>), and NotificationUtils.createNotificationChannel(context, channelName) creates channels with IMPORTANCE_HIGH, which allows heads-up notifications, whenever it's called with the service as its context. The repository's twa-notification-high-priority demo shows the setup.

Verify the result on a device before you rely on heads-up delivery. In the 2.7.3 sources the high-importance helper is used from Android Browser Helper's own code paths, while the androidx TrustedWebActivityService.onNotifyNotificationWithChannel() that actually posts each delegated notification still calls createNotificationChannel() with IMPORTANCE_DEFAULT. Android treats that call on an existing channel as an update, and an update may lower (never raise) the importance of a channel whose settings the user hasn't touched. Send a test push, then open the app's notification settings and check the channel's behavior.

Two Android rules limit what the flag can do. An app can't raise the importance of a channel that already exists, so users who installed an earlier version keep their default-importance channel until they change it in system settings or reinstall. And users can lower any channel's importance at any time. Use high priority for messaging and calls, not for marketing.

<service android:name=".DelegationService" android:exported="true">
    <meta-data android:name="android.support.customtabs.trusted.SMALL_ICON"
        android:resource="@drawable/ic_notification_icon" />
    <meta-data android:name="androidx.browser.trusted.USE_HIGH_PRI_NOTIFICATIONS"
        android:value="true" />
    <intent-filter>
        <action android:name="android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</service>

Delegation support differs by browser: Android Browser Helper's browser-support table lists notification delegation for Chrome, Brave and Vivaldi, but not for Edge or Samsung Internet (see Browser support). On a browser without delegation, notifications are attributed to the browser.

Location delegation¶

With features.locationDelegation.enabled (the "Request geolocation permission?" prompt in init), Bubblewrap adds the com.google.androidbrowserhelper:locationdelegation module. The module declares ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION, adds a PermissionRequestActivity, and registers a LocationDelegationExtraCommandHandler in DelegationService. When the page calls navigator.geolocation.getCurrentPosition() or watchPosition(), the browser sends extra commands (checkAndroidLocationPermission, startLocation, stopLocation) to your app, which asks for the Android location permission if needed and streams positions back from the platform location APIs (or from Google Play services when available).

The benefit is consistency: users see the standard Android location dialog attributed to your app, and the grant shows up in the app's permissions. Your JavaScript stays the same. Handle PERMISSION_DENIED and POSITION_UNAVAILABLE errors as usual, and request location in context, after a user action, because Google Play's policies on location permissions apply to your APK.

Google Play Billing with the Digital Goods API¶

Google Play's payments policy generally requires apps distributed on Play to sell in-app digital goods and subscriptions through Google Play Billing (with regional alternative-billing programs as exceptions). A TWA is an app on Play, so if your PWA sells digital content, the Play version must offer Play Billing. The web platform side is two APIs:

• The Digital Goods API (window.getDigitalGoodsService()), a WICG draft that queries products and existing purchases from a store. It's Chromium-only, enabled by default since Chrome 101 on Android and Chrome 100 on ChromeOS, and only returns a working service when a store backend is connected, which for Play means a TWA with Android Browser Helper's billing module.
• The Payment Request API with the payment method identifier https://play.google.com/billing, which launches the Play purchase sheet.

Enabling billing in the Android app¶

In twa-manifest.json set "features": { "playBilling": { "enabled": true } } (or answer yes to "Include support for Play Billing?"), then run bubblewrap update and bubblewrap build. Bubblewrap 1.25.0 adds com.google.androidbrowserhelper:billing:1.2.0, a PaymentActivity handling org.chromium.intent.action.PAY with org.chromium.default_payment_method_name set to https://play.google.com/billing, a PaymentService handling org.chromium.intent.action.IS_READY_TO_PAY, and registers DigitalGoodsRequestHandler in DelegationService. Older guides, including Chrome's own billing guide, also tell you to enable alphaDependencies; with current Bubblewrap that's no longer needed, since 1.23.0 removed the alpha warnings for billing and the billing module is added whether or not alpha dependencies are on. Two build prerequisites do apply: enableNotifications must be true (the billing handler lives in DelegationService), and minSdkVersion must be at least 23 for billing 1.2.0.

Prerequisites on the Play side: a Play developer account linked to a payments profile, the products or subscriptions created in Play Console, and a release on at least an internal testing track, since billing only works for an app Play knows about. Use license testers to buy without being charged.

API surface¶

ItemDetails has itemId, title, price (a PaymentCurrencyAmount with currency and value), and optionally type ("product" or "subscription"), description, iconURLs, subscriptionPeriod, freeTrialPeriod, introductoryPrice, introductoryPricePeriod and introductoryPriceCycles. Periods are ISO 8601 durations such as P1M.

Behavior changes in billing 1.2.0 (Play Billing Library 8)¶

Google Play requires Play Billing Library 8 or newer for new apps and app updates from August 31, 2026 (an extension to November 1, 2026 can be requested in Play Console). Android Browser Helper's billing module 1.2.0 is the upgrade path, and its migration guide lists two behavior changes that the web API can't express:

• listPurchaseHistory() returns an empty list. Keep your own purchase history on the server, keyed by purchase token.
• Subscriptions are flattened. Play subscriptions are hierarchical (subscription → base plans → offers) while ItemDetails is flat, so getDetails() now returns only the first eligible base plan or offer for each subscription. The old "backward compatible" base plan designation is no longer honored. If you sell several base plans or offers for one subscription, getDetails() can't show them all.

A production purchase flow¶

// Google Play Billing through the Digital Goods API, with a web fallback.
const PLAY_BILLING = "https://play.google.com/billing";

let servicePromise = null;

/** Resolves to a DigitalGoodsService, or null outside a Play-installed TWA. */
export function getPlayBillingService() {
  if (!servicePromise) {
    servicePromise = (async () => {
      if (!("getDigitalGoodsService" in window)) return null;
      try {
        return await window.getDigitalGoodsService(PLAY_BILLING);
      } catch (err) {
        // OperationError: no Play backend (normal browser tab, WebView fallback,
        // or an APK without the billing module). Not an error for us.
        console.info("Play Billing unavailable:", err.name);
        return null;
      }
    })();
  }
  return servicePromise;
}

/** Loads localized prices for the storefront. */
export async function loadCatalog(itemIds) {
  const service = await getPlayBillingService();
  if (!service) return null; // caller renders the web checkout instead
  const items = await service.getDetails(itemIds);
  return items.map((item) => ({
    id: item.itemId,
    title: item.title,
    description: item.description ?? "",
    type: item.type ?? "product",
    period: item.subscriptionPeriod ?? null,
    // Format with Intl using the currency Play returned, not the user's locale currency.
    price: new Intl.NumberFormat(navigator.language, {
      style: "currency",
      currency: item.price.currency,
    }).format(Number(item.price.value)),
  }));
}

/**
 * Starts a purchase. Must run from a user gesture (click handler), because
 * PaymentRequest.show() requires transient user activation.
 */
export async function purchase(itemId, { consumable = false } = {}) {
  const service = await getPlayBillingService();
  if (!service) throw new Error("Play Billing is not available in this context");

  const request = new PaymentRequest(
    [{ supportedMethods: PLAY_BILLING, data: { sku: itemId } }],
    // Required by Payment Request; Play shows its own price, so the amount is ignored.
    { total: { label: "Total", amount: { currency: "USD", value: "0" } } }
  );

  let response;
  try {
    response = await request.show();
  } catch (err) {
    if (err.name === "AbortError") return { status: "cancelled" };
    throw err;
  }

  const { purchaseToken } = response.details;
  let result;
  try {
    // The server verifies the token with the Play Developer API, grants the
    // entitlement (idempotently, keyed by token) and acknowledges the purchase.
    // Unacknowledged purchases are refunded and revoked by Play after three days.
    const res = await fetch("/api/play/purchases", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      credentials: "include",
      body: JSON.stringify({ itemId, purchaseToken }),
    });
    if (!res.ok) throw new Error(`Verification failed: HTTP ${res.status}`);
    result = await res.json(); // { status: "granted" | "pending" | "invalid" | ... }
  } catch (err) {
    await response.complete("fail");
    // The token is still valid: reconcilePurchases() retries on the next launch.
    throw err;
  }

  if (result.status === "pending") {
    // Cash or delayed payment: nothing to grant yet. Play updates the state later,
    // and reconcilePurchases() or a Real-time Developer Notification completes it.
    await response.complete("success");
    return { status: "pending", purchaseToken };
  }
  if (result.status !== "granted") {
    await response.complete("fail");
    return { status: result.status, purchaseToken };
  }

  // Settle the PaymentResponse as soon as the entitlement exists; consuming is separate.
  await response.complete("success");

  if (consumable) {
    try {
      // Only after the server has granted the goods, and never for a pending purchase.
      await service.consume(purchaseToken);
    } catch (err) {
      // Not fatal: the goods are granted. The purchase stays in listPurchases()
      // until consumed, so reconcilePurchases() re-sends it and the server
      // (idempotent per token) answers "granted" again; consume then.
      console.warn("consume() failed, will retry on next launch:", err);
    }
  }
  return { status: "purchased", purchaseToken };
}

/**
 * Call on startup: re-sends every current purchase to the server so purchases
 * interrupted by a crash, a lost connection or a pending payment are granted.
 */
export async function reconcilePurchases() {
  const service = await getPlayBillingService();
  if (!service) return [];
  const purchases = await service.listPurchases();
  const results = await Promise.allSettled(
    purchases.map(async (p) => {
      const res = await fetch("/api/play/purchases", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify({ itemId: p.itemId, purchaseToken: p.purchaseToken }),
      });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      const { status, consumable } = await res.json();
      // The server knows which SKUs are consumable; finish interrupted consumptions.
      if (status === "granted" && consumable) await service.consume(p.purchaseToken);
      return { itemId: p.itemId, status };
    })
  );
  return results
    .filter((r) => r.status === "fulfilled" && r.value.status === "granted")
    .map((r) => r.value.itemId);
}

The server never trusts the client's claim. It asks the Google Play Developer API about the token, checks that the token hasn't been used for another account, grants the entitlement and acknowledges:

import { google } from "googleapis";

const PACKAGE_NAME = "com.example.app.twa";
const auth = new google.auth.GoogleAuth({
  scopes: ["https://www.googleapis.com/auth/androidpublisher"],
});
const publisher = google.androidpublisher({ version: "v3", auth });

/**
 * Verifies and acknowledges a one-time product purchase.
 * @param {{ userId: string, itemId: string, purchaseToken: string, db: object }} input
 * @returns {Promise<{ status: string, consumable?: boolean }>} sent to the client as JSON
 */
export async function handleProductPurchase({ userId, itemId, purchaseToken, db }) {
  const { data } = await publisher.purchases.products.get({
    packageName: PACKAGE_NAME,
    productId: itemId,
    token: purchaseToken,
  });

  // purchaseState: 0 = purchased, 1 = canceled, 2 = pending.
  if (data.purchaseState === 2) return { status: "pending" };
  if (data.purchaseState !== 0) return { status: "invalid" };

  // Bind the token to one account; replayed tokens from other accounts are rejected.
  // claimPurchaseToken() is an atomic insert-if-absent that returns the owning user.
  const owner = await db.claimPurchaseToken(purchaseToken, userId, itemId);
  if (owner !== userId) return { status: "token-already-used" };

  // Idempotent per token: reconcilePurchases() re-sends tokens on every launch, so a
  // second call for the same token must not grant the goods twice.
  await db.grantEntitlementOnce(purchaseToken, userId, itemId, { orderId: data.orderId });

  // acknowledgementState: 0 = not yet acknowledged, 1 = acknowledged.
  if (data.acknowledgementState === 0) {
    await publisher.purchases.products.acknowledge({
      packageName: PACKAGE_NAME,
      productId: itemId,
      token: purchaseToken,
      requestBody: {},
    });
  }
  // consumptionState: 0 = not yet consumed. Tells the client whether to call consume().
  return { status: "granted", consumable: db.isConsumable(itemId) && data.consumptionState === 0 };
}

Subscriptions use purchases.subscriptionsv2.get (state in subscriptionState, for example SUBSCRIPTION_STATE_ACTIVE) and purchases.subscriptions.acknowledge, and you should also consume Real-time Developer Notifications to learn about renewals, cancellations and refunds that happen while the app is closed. Pending purchases (a cash payment at a store, for example) resolve later; that's why reconcilePurchases() runs on every launch.

To test a build you installed yourself (with bubblewrap install or adb install), enable chrome://flags/#enable-debug-for-store-billing in Chrome 101 or later on the device; the Chrome documentation notes the flag "is not required when the application is downloaded from the Play Store." Either way, the package and its products must exist in Play Console on at least an internal testing track, and the Google account on the device should be a license tester so purchases aren't charged.

Other integrations: shortcuts, sharing, files, protocols and messaging¶

Many manifest features have a native counterpart in the APK. Bubblewrap generates them from your web manifest; the web side keeps working as documented in each feature's page.

postMessage between the app and the page¶

Since Chrome 115.0.5790.13, a native app can open a message channel to the page in its TWA or Custom Tab. The app binds to the Custom Tabs service, calls warmup(), creates a session, asks the browser to verify its claim on the source origin with session.validateRelationship(CustomTabsService.RELATION_USE_AS_ORIGIN, sourceOrigin, null) (the result arrives in onRelationshipValidationResult()), waits for onNavigationEvent(NAVIGATION_FINISHED), then calls session.requestPostMessageChannel(sourceOrigin, targetOrigin, extras); when onMessageChannelReady() fires it can postMessage(), and replies arrive in onPostMessage(). It requires androidx.browser 1.6.0-alpha02 or later, the androidx.browser.customtabs.PostMessageService declared in the manifest, and a delegate_permission/common.use_as_origin statement for the app in the site's assetlinks.json, so that the browser can report the app's origin as event.origin.

On the page, the first message delivers a MessagePort:

// Receives the MessagePort the Android app opens after the page loads.
const APP_ORIGIN = "https://app.example.com"; // the source origin the app validated

let port = null;
const handlers = new Map();

window.addEventListener("message", (event) => {
  if (event.origin !== APP_ORIGIN || !event.ports?.length) return;
  port = event.ports[0];
  port.onmessage = ({ data }) => {
    let message;
    try {
      message = typeof data === "string" ? JSON.parse(data) : data;
    } catch {
      return; // ignore malformed input from the native side
    }
    handlers.get(message.type)?.(message.payload);
  };
  port.postMessage(JSON.stringify({ type: "ready" }));
});

export function onNativeMessage(type, handler) {
  handlers.set(type, handler);
}

export function sendToNative(type, payload) {
  if (!port) return false; // not in an app that opened a channel
  port.postMessage(JSON.stringify({ type, payload }));
  return true;
}

Messages are strings on the Android side, so serialize to JSON. Treat everything from the channel as untrusted input, like any postMessage traffic.

Multiple origins in one TWA¶

If your app spans origins (a separate login or checkout host, a regional domain), list them in additionalTrustedOrigins. Bubblewrap then writes the ADDITIONAL_TRUSTED_ORIGINS string array, an extra asset_statements entry and an App Links intent filter for each. Every origin must serve its own assetlinks.json with the app's package and fingerprints; the Chrome documentation's rule is that "an application using Trusted Web Activities can have any number of validated domains, as long as Digital Asset Links are implemented for all of them." Origins you don't control, such as an identity provider, can't be verified, and the user sees the Custom Tabs toolbar while on them, which is the intended security signal.

When you configure the launch in code, pass the list with TrustedWebActivityIntentBuilder.setAdditionalTrustedOrigins(List<String>).

Updating a TWA¶

A TWA has two update channels, and only one needs Google Play:

bubblewrap update increments appVersionCode by one on each run (unless you pass --skipVersionUpgrade) and asks for a versionName; if the old versionName equaled the old code, it defaults the new name to the new code. bubblewrap play versionCheck compares your local version code with the highest one on Play, which helps when several machines build releases.

The yearly Play requirements are the main reason to touch the APK. From August 31, 2026, new apps and app updates must target API level 36 (Android 16), and existing apps must target at least API level 35 to stay available to new users on newer Android versions. Bubblewrap 1.25.0's template targets 36, so upgrading the CLI and running update is usually enough. Because update regenerates the Android project from templates, any manual edits to Gradle, Java or XML files are overwritten; keep manual customizations in a patch you re-apply, or move to a hand-maintained project.

For the web-side view of identity and updates (the manifest id, icon updates for browser-installed apps), see App Identity & Updates.

ChromeOS, Meta Quest and large screens¶

TWAs published on Google Play are also offered on Chromebooks that run Android apps. On ChromeOS the Android side runs in ARC (the Android runtime for ChromeOS), and Android Browser Helper contains ChromeOS-specific paths: it detects the org.chromium.arc system feature, launches the content through a Custom Tabs intent flagged to launch as a TWA (a code comment notes that "ARC++ does not support native TWAs at the moment"), and registers org.chromium.arc.payment_app as the verified provider for billing requests. The webManifestUrl in twa-manifest.json exists for this case; Bubblewrap's template describes it as "used by Chrome OS and Meta Quest to open the Web version of the PWA instead of the TWA, as it will probably give a better user experience for non-mobile devices."

Publishing specifics from Google's ChromeOS documentation:

• bubblewrap init --chromeosonly (or <uses-feature android:name="org.chromium.arc" android:required="true"/>) restricts the package to ChromeOS devices.
• If the store listing also has a phone app, the ChromeOS-only package's version code must be higher than the Android app's. Uploading a mobile package with a higher version code than a ChromeOS-only package that also runs on Chromebooks replaces it there.
• Play Billing through the Digital Goods API works on ChromeOS (Chrome 100+).
• Google doesn't recommend the "paid app" model for PWAs on Play, because the web content itself can't verify the purchase.

bubblewrap init --metaquest builds for Meta Quest headsets, with minSdkVersion 23, hand-tracking features and com.oculus.pwa.NAME, START_URL and SCOPE metadata. For the desktop-class form factors themselves, see Desktop Platforms.

TWA vs WebAPK vs WebView vs Custom Tab¶

Four ways a PWA can end up behind an Android icon, compared:

Rules of thumb:

• You need a store listing, Play Billing, or native extension points (a native screen, a native SDK for something the web can't do): TWA.
• You want installation from the web with zero Android tooling: let Chrome mint a WebAPK; see Installation by Platform and Android.
• You ship both (common): the Play TWA and the WebAPK coexist. Declare the Play app in related_applications so you can detect it from the browser, and remember that both use the same browser storage for your origin when Chrome is the TWA provider.
• Your content must work without a browser, or you need deep native integration on every screen: a WebView-based or native app, which is a different architecture; see PWA vs Native vs Hybrid.

Browser support¶

TWA is an Android protocol, so "browser support" means which Android browsers implement the provider side. Android Browser Helper maintains this table in its repository: