Mind-o-Mat/webapp/TWA-BUILD.md

TWA Build-Anleitung (Phase 5)

Diese Anleitung erklärt, wie die Mind-o-Mat PWA in eine native Android-App (TWA = Trusted Web Activity) verpackt wird, um sie im Google Play Store zu veröffentlichen.

Schnellstart (mit Build-Script)

# 1. Webapp bauen
cd webapp && npm run build

# 2. TWA bauen (PWA-Build vorausgesetzt)
npm run build:twa

Das Script versucht zuerst bubblewrap (Standard), fällt auf PWABuilder.com zurück.

Voraussetzungen

Voraussetzungen

• Node.js 18+ (für Bubblewrap CLI)
• Java JDK 17+ (für Android-Build)
• Android SDK mit Build-Tools 33+
• Google Play Console Account (25 USD einmalig)
• Mind-o-Mat Vault mit öffentlicher HTTPS-URL (für TWA-Validierung)

Schritt 1: App-Inhalte vorbereiten

Die PWA muss auf einer HTTPS-Domain gehostet sein, damit TWA funktioniert. Die assetlinks.json (in public/.well-known/) muss von dieser Domain ausgeliefert werden.

Selbst-Hosting mit gitea Pages, Netlify oder eigenem Server: Siehe externe Anleitungen, ist nicht Teil dieses Repos.

Schritt 2: Bubblewrap installieren

npm install -g @nicejob/nicejob-cli
# oder
npm install -g @nicejob/nicejob
# Bubblewrap: https://github.com/nicejob/bubblewrap

Schritt 3: TWA-Manifest konfigurieren

Die Datei twa-manifest.json enthält die App-Konfiguration. Wichtig:

• packageId: Android Package-ID (z. B. de.jannik.mindomat)
• host: Domain, unter der die PWA läuft (z. B. vault.mindomat.de)
• webManifestUrl: URL zur manifest.webmanifest
• sha256CertFingerprints: SHA-256-Fingerabdruck des Signing-Certs

Schritt 4: SHA-256-Fingerprint ermitteln

# Lokal:
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android
# SHA256: XX:XX:XX:...

# Für Play Store: eigenes Signing-Key erstellen
keytool -genkey -v -keystore release-key.keystore -alias mindomat -keyalg RSA -keysize 2048 -validity 10000

Den ermittelten Fingerabdruck in twa-manifest.json und assetlinks.json eintragen.

Schritt 5: TWA bauen

bubblewrap build --manifest=twa-manifest.json
# Erzeugt: app-release-bundle.aab (für Play Store) und app-release-signed.apk

Schritt 6: Play Store

1. Google Play Console öffnen
2. Neue App erstellen mit der packageId
3. App-Bundle (app-release-bundle.aab) hochladen
4. Store-Eintrag ausfüllen (Screenshots, Beschreibung, Datenschutz)
5. SHA-256-Fingerprint in "App-Signatur" hinterlegen
6. assetlinks.json auf der Hosting-Domain verifizieren lassen
7. Review abschicken

Schritt 7: Updates

Bei App-Updates:

1. TWA-Manifest versionCode und versionName erhöhen
2. bubblewrap build neu ausführen
3. Bundle in Play Console hochladen

Bekannte Einschränkungen

• Push-Notifications: TWA unterstützt sie, müssen aber in der PWA via Service Worker implementiert sein.
• File-System-Access: Browser-APIs sind eingeschränkt. Für vollen File-Zugriff wäre Capacitor.js nötig (Alternative).
• Background-Sync: Nur eingeschränkt möglich.

Alternative: Capacitor.js

Falls TWA zu eingeschränkt ist, kann Capacitor.js als Wrapper verwendet werden. Es bietet native Plugins für Camera, Filesystem, etc. und ist die „nächste Stufe" über TWA hinaus.