werkstaetten-app/mobile/README.md
Friederich Loheide 856559f830 Native Apps für iOS und Android (Capacitor) mit Push über Firebase
Apps (mobile/):
- Capacitor-8-Hülle, lädt die Web-App von APP_URL – Inhalte ohne App-Update
- Android- und iOS-Projekt (Swift Package Manager) mit Firebase Messaging,
  nativer Sprachausgabe, Teilen, App, Statusleiste, Startbildschirm
- `npm run sync` überträgt APP_ID, Name, Adresse und Farbe aus mobile/.env
  in beide Projekte und richtet ein: App-Links (Android intent-filter,
  iOS Associated Domains), Push (Entitlements, Background Mode,
  AppDelegate, Benachrichtigungssymbol/-farbe), Offline-Seite;
  idempotent, prüft Eingaben, warnt bei fehlenden Firebase-Dateien
- `npm run assets` erzeugt Symbole und Startbildschirme aus Logo und
  Markenfarbe der Redaktion, dazu das Android-Benachrichtigungssymbol
- Schritt-für-Schritt-Anleitung für den Mac (mobile/README.md)

Server:
- Versand an App-Geräte über FCM HTTP v1 (signiertes JWT, ohne
  firebase-admin), eingebunden in alle Benachrichtigungen; abgemeldete
  Geräte werden entfernt (nur bei UNREGISTERED, nicht bei anderen Fehlern)
- Firebase-Dienstkonto in den Einstellungen hochladen (verschlüsselt),
  App-ID, Team-ID, SHA-256, Store-Links; /.well-known/apple-app-site-
  association und assetlinks.json; Smart-App-Banner, Store-Hinweis
- Server erkennt die App am User-Agent (kein Aufblitzen von
  „Als App installieren“); Datenschutz-Vorlage um Firebase ergänzt

Web-App in der App: Push über Firebase statt Web-Push, Vorlesen nativ,
Teilen nativ, Zurück-Taste (schließt erst Dialoge), Antippen einer
Benachrichtigung und App-Links öffnen die Seite (nur eigene Adressen).

Getestet mit nachgebauter Capacitor-Brücke und nachgebautem Firebase-Dienst.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-03 07:03:26 +00:00

165 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Native Apps (iOS und Android)
Die Apps sind eine **Capacitor-Hülle** um die Web-App: Sie laden die Inhalte von eurem Server
(`APP_URL`). Was die Redaktion veröffentlicht, erscheint sofort in Web, iPhone und Android –
ohne App-Update. Dazu kommen native Funktionen:
- **Push-Nachrichten** über Firebase Cloud Messaging (Android) bzw. Apple Push über Firebase (iPhone) –
dieselben Themen, Zeitpläne und „Benachrichtigung senden“ wie im Browser
- **Vorlesen** mit der Sprachausgabe des Geräts (Android-WebViews haben keine eigene)
- **App-Links**: Links zu `APP_URL` öffnen direkt die App (außer `/admin`)
- natives Teilen, Zurück-Taste (Android), Statusleiste passend zum Farbschema, Startbildschirm,
Offline-Seite, Symbol aus Logo und Markenfarbe der Redaktion
Ein App-Update braucht ihr nur, wenn sich am nativen Teil etwas ändert (neue Plugins, neue
Capacitor-Version, neues Symbol).
---
## Einmalig vorbereiten
### Das braucht ihr
| Was | Wofür | Kosten |
| --- | --- | --- |
| Mac mit aktuellem **Xcode** | iOS-App bauen | – |
| **Android Studio** (auch auf dem Mac) | Android-App bauen | – |
| **Node.js 22** oder neuer | Skripte | – |
| **Apple Developer Program** (möglichst als Organisation) | App Store, Push auf dem iPhone | 99 € / Jahr |
| **Google Play Console** | Play Store | einmalig 25 $ |
| **Firebase-Projekt** | Push-Nachrichten | kostenlos |
| Web-App läuft unter einer **HTTPS-Adresse** | Die Apps laden die Inhalte von dort | – |
### 1. Projekt einrichten
```bash
git clone git.loheide.cloud:friloo/werkstaetten-app.git
cd werkstaetten-app/mobile
npm install
cp .env.example .env
```
In `mobile/.env` eintragen:
- `APP_URL` – Adresse der Web-App, z. B. `https://app.lindenhof.de`
- `APP_ID` – eindeutige Kennung, z. B. `org.lindenhof.app`. **Vor dem ersten Hochladen festlegen –
danach nicht mehr änderbar.**
- `APP_NAME` – Name unter dem Symbol (kurz halten, max. ca. 12 Zeichen sichtbar)
- `BRAND_COLOR` – Markenfarbe für Startbildschirm und Symbol
Dann Symbole und Startbildschirm erzeugen (holt Logo und Farbe von der laufenden Web-App) und die
Projekte vorbereiten:
```bash
npm run assets
npm run sync
```
`npm run sync` überträgt die Werte aus `.env` in beide Projekte und richtet Push und App-Links ein.
Es kann beliebig oft ausgeführt werden – **nach jeder Änderung an `.env` erneut ausführen.**
### 2. Firebase (Push-Nachrichten)
1. [Firebase-Konsole](https://console.firebase.google.com) → **Projekt hinzufügen** (Google Analytics wird nicht gebraucht).
2. **Android-App hinzufügen** – Paketname = `APP_ID` → `google-services.json` herunterladen →
nach `mobile/android/app/google-services.json` legen.
3. **iOS-App hinzufügen** – Bundle-ID = `APP_ID` → `GoogleService-Info.plist` herunterladen →
nach `mobile/ios/App/App/GoogleService-Info.plist` legen **und in Xcode** (`npm run open:ios`) aus dem
Finder in den Ordner **App/App** ziehen („Copy items if needed“ aus, Ziel **App** angehakt).
4. **Apple-Push-Schlüssel**: Im [Apple-Developer-Konto](https://developer.apple.com/account/resources/authkeys/list)
unter *Keys* einen Schlüssel mit **Apple Push Notifications service (APNs)** erstellen, `.p8` herunterladen.
In Firebase: *Projekteinstellungen → Cloud Messaging → Apple-App-Konfiguration →
APNs-Authentifizierungsschlüssel* hochladen (mit Key-ID und Team-ID).
5. **Dienstkonto für den Server**: *Projekteinstellungen → Dienstkonten → Neuen privaten Schlüssel
generieren*. Die JSON-Datei in der Redaktion unter **Einstellungen → Apps** hochladen
(wird verschlüsselt gespeichert). Die Datei danach vom Rechner löschen.
Die beiden Firebase-Dateien aus 2. und 3. sind absichtlich nicht im Git-Repository.
### 3. In der Redaktion eintragen
**Einstellungen → Apps (iOS und Android):**
- **App-ID** = `APP_ID`
- **Apple Team-ID** (Apple-Developer-Konto → *Membership*)
- **Android SHA-256**: nach dem ersten Hochladen in die Play Console unter
*Einrichten → App-Integrität → App-Signaturschlüsselzertifikat*. Für Tests mit eigenen Builds
zusätzlich den Fingerabdruck eures Upload-Schlüssels (eine Zeile pro Fingerabdruck).
- **Store-Links**, sobald die Apps veröffentlicht sind – dann weist die Website auf die Apps hin
und Safari zeigt das App-Banner.
Prüfen, ob die App-Links-Nachweise ausgeliefert werden:
```bash
curl https://app.lindenhof.de/.well-known/apple-app-site-association
curl https://app.lindenhof.de/.well-known/assetlinks.json
```
---
## iOS bauen
```bash
npm run sync
npm run open:ios
```
In Xcode:
1. Ziel **App** → **Signing & Capabilities** → *Team* wählen.
2. Prüfen, dass diese Fähigkeiten aktiv sind (sie stehen bereits in `App.entitlements` bzw.
`Info.plist`; falls Xcode sie nicht anzeigt, mit **+ Capability** hinzufügen):
**Push Notifications**, **Background Modes → Remote notifications**, **Associated Domains**
(`applinks:<eure Domain>`).
3. Auf einem **echten iPhone** testen (Push ist im Simulator nur eingeschränkt möglich).
4. Veröffentlichen: **Product → Archive → Distribute App → App Store Connect** → in
App Store Connect über **TestFlight** testen, dann zur Prüfung einreichen.
`aps-environment` steht auf `development`; beim Archivieren für den App Store setzt Xcode
automatisch `production`.
## Android bauen
```bash
npm run sync
npm run open:android
```
In Android Studio:
1. Mit einem Android-Handy (USB-Debugging) oder Emulator **Run ▶** – zum Testen.
2. Veröffentlichen: **Build → Generate Signed App Bundle** → neuen Schlüsselspeicher (Keystore)
anlegen. **Keystore und Passwörter sicher aufbewahren** – ohne sie keine Updates.
3. Das `.aab` in der **Play Console** hochladen (zuerst „Interner Test“), *Play App Signing*
aktiviert lassen. Danach den SHA-256 aus der Play Console in der Redaktion eintragen (siehe oben).
---
## Prüfung durch Apple und Google
- **Apple (Richtlinie 4.2 „Minimum Functionality“)**: Reine Website-Hüllen lehnt Apple ab. In die
Prüfnotizen schreiben, was die App nativ kann: Push-Nachrichten zu Schließzeiten und Neuigkeiten,
Vorlesen mit der Sprachausgabe des Geräts, Leichte Sprache, Teilen, Offline-Hinweis.
Ein Testzugang ist nicht nötig – die App hat keine Anmeldung.
- **Datenschutzangaben** (App Store „App Privacy“ / Google „Datensicherheit“):
erhoben wird nur eine **Gerätekennung für Push-Nachrichten** (nicht mit einer Person verknüpft,
kein Tracking). Inhalte aus Kontakt- und Barriere-Formular: Name, E-Mail (optional), Nachricht –
nur zur Bearbeitung der Anfrage. Keine Werbung, keine Analyse.
- Als Datenschutzerklärung `APP_URL/datenschutz` angeben; als Support-Adresse `APP_URL/kontakt`.
## Updates
- **Inhalte**: kein App-Update nötig.
- **Native Teile** (Plugins, Capacitor, Symbol, Name): im Ordner `mobile/`
`npm install`, ggf. `npm run assets`, dann `npm run sync`, neu bauen und hochladen.
Für jede neue Version in Xcode *Version/Build* bzw. in `android/app/build.gradle`
`versionCode`/`versionName` erhöhen.
## Wenn etwas nicht klappt
| Problem | Prüfen |
| --- | --- |
| Keine Push-Nachrichten | Firebase-Dateien vorhanden? APNs-Schlüssel in Firebase? Dienstkonto in der Redaktion? In der App unter *Einstellungen → Benachrichtigungen* eingeschaltet? |
| Links öffnen den Browser statt der App | `.well-known`-Dateien abrufbar (siehe oben)? Team-ID / SHA-256 korrekt? Android: *Einstellungen → Apps → App → Standardmäßig öffnen*. |
| „Keine Verbindung“ obwohl online | Läuft die Web-App unter `APP_URL` mit gültigem HTTPS-Zertifikat? |
| Android: Benachrichtigungssymbol ist ein weißes Quadrat | `npm run assets` ausführen, dann `npm run sync`. |