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

7.6 KiB
Raw Blame History

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

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:

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 → 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 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:

curl https://app.lindenhof.de/.well-known/apple-app-site-association
curl https://app.lindenhof.de/.well-known/assetlinks.json

iOS bauen

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

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.