thermograph/infra/deploy/twa/README.md

# Thermograph Android app (Trusted Web Activity)

The Android app is a **Trusted Web Activity (TWA)**: a thin native shell that opens
`https://thermograph.org` full-screen in the user's Chrome engine. It *is* the live
PWA — no content is duplicated, and the existing service worker + VAPID **web push
keeps working** inside the app via Android notification delegation (no Firebase, no
backend change). `enableNotifications: true` in `twa-manifest.json` turns that on
and wires the Android 13+ `POST_NOTIFICATIONS` runtime permission.

This folder holds the build config. **Building the APK is a local/manual step** —
it needs a JDK, the Android SDK, and a signing keystore that only you should hold.
The current goal is a **signed APK you sideload for testing**; Play Store
submission ($25 one-time) is deferred.

## What's in the repo
- `twa-manifest.json` — Bubblewrap config (reference values; see comment inside).
- `../../../frontend/static/.well-known/assetlinks.json` — Digital Asset Links, served at
  `https://thermograph.org/.well-known/assetlinks.json`. Its fingerprint is a
  **placeholder** until you generate the signing key (step 4).

## One-time build (you)

Prereqs: Node 18+, JDK 17. Bubblewrap can download the Android SDK for you.

```bash
npm install -g @bubblewrap/cli

# 1. Scaffold from the live manifest (creates ./twa-manifest.json + a keystore).
#    Accept defaults, then reconcile with this repo's twa-manifest.json — in
#    particular set:  packageId = org.thermograph.twa,  enableNotifications = true.
bubblewrap init --manifest https://thermograph.org/manifest.webmanifest

# 2. (Or) copy this repo's config and let Bubblewrap fill the SDK bits:
#    cp deploy/twa/twa-manifest.json ./twa-manifest.json && bubblewrap update

# 3. Build the signed APK (and .aab for the store, for later).
bubblewrap build
#    -> ./app-release-signed.apk  and  ./app-release-bundle.aab
```

### 4. Wire Digital Asset Links (required — or the app opens with a URL bar)

```bash
# Print the signing key's SHA-256 fingerprint:
bubblewrap fingerprint list          # or: keytool -list -v -keystore android-keystore.jks
```

Copy the `SHA256` value into `frontend/static/.well-known/assetlinks.json`, replacing
`REPLACE_WITH_TWA_SIGNING_KEY_SHA256_FINGERPRINT`, then **deploy the site** so the
new file is live. Confirm:

```bash
curl -s https://thermograph.org/.well-known/assetlinks.json    # must show your fingerprint, Content-Type: application/json
```

> If you later publish to Play Store with **Play App Signing**, add *Google's* app
> signing certificate fingerprint (from the Play Console) to `assetlinks.json` too —
> the upload-key fingerprint alone won't verify the store build.

### 5. Sideload and test

```bash
adb install app-release-signed.apk
```

On the device:
- Launch Thermograph — it must open **full-screen with no browser address bar**
  (that confirms assetlinks verified).
- Subscribe to a city (or trigger a test alert) and confirm the "unusual weather"
  push arrives as a **native Android notification**.
- Grant the notifications permission when prompted (Android 13+).

## Keep the keystore safe
`android-keystore.jks` is required for **every future update** and for the
eventual Play Store listing. Losing it means a new package identity and a fresh
install for every user. Store it out of the repo, backed up.

## Deferred
- **Play Store listing** ($25 one-time Google Play developer account). Upload the
  `.aab`; the store review for a well-formed TWA is light. Not part of this pass.

## Why no backend changes
Android delegates the TWA's web notifications to the OS, so
`backend/notifications/push.py` (VAPID) and `backend/notifications/notify.py`
deliver push to the app unchanged. Nothing in
`backend/` is touched by this track.