werkstaetten-app/mobile/README.md
Friederich Loheide 21a54da2e3 Erscheinungsbild je Einrichtung: Vorlagen, Schriften, Farben, mehrere Installationen
- Drei Design-Vorlagen (Kreis, Klar, Kacheln) mit Feinschliff: vier gut lesbare
  Schriften, eckig/rund/sehr rund, Hausfarben mit Live-Kontrastprüfung und
  „Farbe anpassen“; der Server lehnt zu helle Farben mit Vorschlag ab
- Fertige Farbpaare alle mit mindestens 4,5:1 zu Weiß
- Markenfarben greifen jetzt zuverlässig (Spezifität der eingebetteten Variablen);
  dunkle Darstellung wird aus der Hauptfarbe abgeleitet statt fest Indigo
- Checkliste „Erste Schritte“ im Dashboard für neue Einrichtungen
- Startwerte (APP_NAME, ORG_NAME, BRAND_COLOR, ACCENT_COLOR) beim ersten Start
- deploy/: neue-einrichtung.sh, aktualisieren.sh, sichern.sh für eine
  Installation je Kunde mit gemeinsamem Image
- mobile/: KUNDE=<kurzname> baut die App einer Einrichtung aus mobile/kunden/<kurzname>/
  inklusive deren Firebase-Dateien

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-09 17:54:11 +00:00

190 lines
8.7 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.
## Mehrere Einrichtungen
Jede Werkstatt bekommt ihre eigene App im Store (eigene App-ID, eigener Name, eigenes Symbol,
eigenes Firebase-Projekt). Statt `mobile/.env` gibt es dann je Einrichtung einen Ordner:
```
mobile/kunden/lindenhof/.env ← wie .env.example
mobile/kunden/lindenhof/google-services.json ← Firebase, Android
mobile/kunden/lindenhof/GoogleService-Info.plist ← Firebase, iOS
```
Gebaut wird immer eine Einrichtung nach der anderen:
```bash
KUNDE=lindenhof npm run assets # Symbole aus deren Web-App holen
KUNDE=lindenhof npm run sync # ID, Name, Farbe, Firebase-Dateien übernehmen
npm run open:ios # bzw. open:android → bauen und hochladen
```
`npm run sync` kopiert die Firebase-Dateien der Einrichtung an die richtige Stelle und entfernt
die einer anderen – Push-Anmeldungen landen so nie im falschen Projekt. Stammen die Symbole noch
von einer anderen Einrichtung, gibt es einen Hinweis. Der Ordner `kunden/` wird nicht eingecheckt
(Vorlage: `kunden/beispiel/`). Signier-Schlüssel (Android-Keystore, Apple-Zertifikate) je
Einrichtung sicher aufbewahren.
## 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`. |