# Eine Android / iOS App für Gladys: Ansatz und erste Ergebnisse **URL:** \ **Category:** Développement\ **Created:** [30. August 2026 um 14:49 UTC](https://community.gladysassistant.com/t/une-application-mobile-android-ios-pour-gladys-approche-et-premiers-resultats/10769 "2026-08-30T14:49:39Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![Will\_71](https://gladys-assistant-community.b-cdn.net/user_avatar/community.gladysassistant.com/will_71/32/9582_2.png) [@Will\_71](https://community.gladysassistant.com/u/Will_71)\ **Post date:** [30. August 2026 um 14:49 UTC](https://community.gladysassistant.com/t/une-application-mobile-android-ios-pour-gladys-approche-et-premiers-resultats/10769/1 "2026-08-30T14:49:40Z")
Hallo zusammen, Nach dem Live-Stream von gestern und der Anforderung einer mobilen Anwendung habe ich Claude einfach mal auf das Thema angesetzt, nur um zu sehen. In weniger als 15 Minuten hat er eine vollständige Spezifikation und eine Demo auf meinem Android-Telefon erstellt, auf der ich meine Dashboards, Szenen… alles von Gladys wiederfinde. Ich bin sprachlos… 🤩 ![image](https://gladys-assistant-community.b-cdn.net/uploads/default/original/3X/c/8/c8f91b1405b715a69aff64d238d9fd9069256fcc.jpeg) Hier ist seine Analyse: _ **Das „ich“ in der Nachricht ist Claude, ich hätte das in 15 Minuten nicht schaffen können.** _ Ich habe mit der Arbeit an einer nativen mobilen Anwendung für Gladys begonnen und möchte den Ansatz teilen, bevor ich weitergehe — insbesondere die Architekturwahl, die mir der diskutabelste Punkt zu sein scheint und daher der, bei dem euer Feedback am nützlichsten wäre. Die Basis funktioniert: Die App läuft auf meinem Telefon, verbunden mit meiner Instanz, mit allen meinen Dashboards und Kameras. * * * ## Das Problem Heute ist Gladys auf mobilen Geräten entweder der Browser oder das Hinzufügen zum Startbildschirm. Das funktioniert, aber es hat Grenzen: - keine zuverlässigen Benachrichtigungen; - kein Hintergrund-Präsenz-Tracking; - keine Präsenz in den Stores; - und der aktuelle Service Worker (`front/old-sw.js`) deinstalliert sich absichtlich bei jeder Aktivierung — es gibt also keine nutzbare PWA-Basis, auf der man aufbauen könnte. * * * ## Die Architekturwahl: Integration des bestehenden Frontends Das ist die entscheidende Entscheidung. Drei Optionen standen zur Auswahl. ### Option A — React Native, eine separate native App Eine neu geschriebene App, die die REST-API und das WebSocket von Gladys nutzt. Bessere Leistung, echtes natives Gefühl. Aber man muss **die gesamte** Oberfläche neu schreiben: 23 Routen, 22 Widget-Typen für Dashboards, den Szenen-Editor, die Karte, den Chat, die Integrationsseiten. Und vor allem muss man **zwei Oberflächen parallel pflegen** : Jede Änderung der Web-Oberfläche müsste manuell in die mobile App übertragen werden, mit dem Risiko von Divergenzen, das damit einhergeht. Für ein Community-Projekt erscheint mir das auf Dauer nicht tragbar. ### Option B — PWA verbessern Service Worker reparieren, Offline-Cache und Web Push hinzufügen. Leicht, kein Store-Management nötig. Aber das löst weder die Hintergrund-Geolokalisierung, noch die Startbildschirm-Widgets, noch die Präsenz in den Stores. Und auf iOS bleibt Web Push eingeschränkt. Man würde mit denselben Grenzen bleiben. ### Option C — Capacitor + bestehendes Frontend ← **ausgewählt** Das aktuelle Gladys-Frontend (Preact / Vite) wird **genau wie heute** kompiliert und dann in einer nativen WebView durch Capacitor eingebettet. Die Fähigkeiten, die das Web nicht bieten kann, werden über Plugins hinter einer Abstraktionsschicht bereitgestellt. ```auto front/ (Preact, unverändert) └── build/ ──> Capacitor WebView ├── android/ └── ios/ + native Plugins: Push, Geolokation, Biometrie, mDNS, sicherer Speicher, Widgets ``` **Warum diese Wahl:** - **Ein einzelner Codebase.** Jede Änderung des Frontends profitiert dem Web, Android und iOS ohne Portierung. Das ist der entscheidende Punkt für ein Community-Projekt. - **Fast vollständige Wiederverwendung.** Bildschirme, Widgets, Aktionen, Übersetzungen, dunkles Thema: Alles wird unverändert übernommen. - **Nichts verloren auf der nativen Seite.** Push-Benachrichtigungen, Geolokalisierung durch Zonen, Biometrie, mDNS-Entdeckung, Startbildschirm-Widgets bleiben über die Plugins zugänglich. - **Umkehrbar.** Falls der Ansatz seine Grenzen zeigt, bleibt das Frontend das Frontend — es wurde keine parallele Schuldenlast geschaffen. **Das Leitprinzip:** Die native Hülle enthält **keine Geschäftslogik**. Sie stellt Fähigkeiten bereit, das Frontend nutzt sie. Jede native Funktionalität ist optional, und ihr Fehlen (abgelehntes Berechtigung, nicht kompatible Plattform) bricht die Anwendung nie. * * * ## Was bereits umgesetzt wurde: Die Verbindungsgrundlage Der erste Teil beantwortet eine Frage, die das Web-Frontend nie stellt: **mit welcher Instanz soll kommuniziert werden?** Im Web ist die Antwort trivial — das Frontend wird von der Instanz selbst bereitgestellt. Eine mobile App hingegen wird in einem einzigen Build für alle verteilt und muss vom Benutzer konfiguriert werden. Konkreter: - **Konfiguration zur Laufzeit.** `front/src/config.js` las `process.env`, das Vite durch Literale beim Build ersetzt. Das exportierte Objekt ist nun veränderbar, mit einer weißen Liste: Nur die Verbindungsschlüssel können überschrieben werden, damit ein fehlerhaft gespeichertes Profil den Demo-Modus nicht aktivieren kann. - **Erstverbindungsbildschirm** , der die Adresse der Instanz anfordert, mit Adresstest vor der Speicherung. - **Multi-Instanz-Profile** (Hauptwohnsitz, Nebenwohnsitz, Testinstanz), gespeichert im Keychain / Keystore. - **Automatischer Wechsel** zwischen lokalem Netzwerk und Gladys Plus, mit einer Sonde auf `/api/v1/ping`. - **Einstellungenseite** zum Verwalten dieser Instanzen — auf dem Web verborgen, wo sie keinen Sinn ergeben würde. **Auswirkung auf das Web-Frontend: null.** Der native Code wird vollständig aus dem Web-Bundle durch Tree-Shaking entfernt, und die Build-Werte bleiben dieselben. Manuell überprüft im Browser. * * * ## Drei Dinge, die die Spezifikation nicht vorhergesehen hat Das ist der lehrreichste Teil und der, der anderen helfen kann. ### 1. Die Mixed-Content-Regel und der Kompromiss, den sie erfordert Damit die Ende-zu-Ende-Verschlüsselung von Gladys Plus funktioniert, wird `crypto.subtle` benötigt, das nur in einem **sicheren Kontext** verfügbar ist. Capacitor erhält dies, indem es die WebView über `https://localhost` bereitstellt. Allerdings kann eine Seite `https://` weder `http://` noch `ws://` aufrufen — Chromium blockiert dies. Eine lokale Gladys-Instanz ist jedoch sehr oft in einfachem HTTP. Die Netzwerksicherheitseinstellungen von Android ändern daran nichts: Es ist eine Richtlinie des Browsers, nicht der Plattform. Das Plugin `CapacitorHttp` löst das Problem der HTTP-Anfragen (sie verlassen die native Schicht), **aber nicht das der WebSockets** , die weiterhin blockiert werden. Ohne WebSocket keine Echtzeit. Daher die Abwägung, die man kennen muss: | `androidScheme` | Sicherer Kontext | Gladys Plus | Lokales HTTP | WebSocket | | --- | --- | --- | --- | --- | | `https` | ja | OK | über CapacitorHttp | **blockiert** | | `http` | nein | **nicht verfügbar** | OK | OK | **Für diesen ersten Teil habe ich `http` gewählt** : Das Ziel war die Verbindung zur lokalen Instanz, die das WebSocket erfordert. Es ist explizit temporär. Die saubere Lösung ist, die Instanz über einen Reverse-Proxy (Caddy, nginx, Traefik) in HTTPS zu servieren: Alles läuft dann über `https`/`wss`, keine Blockaden mehr, sicherer Kontext erhalten. Das ist auch der einzige Weg, der für iOS gelten wird. **Wenn ihr dazu eine Meinung habt, interessiert mich das sehr** : Sollte man annehmen, dass eine Instanz in HTTPS für die Nutzung von Gladys Plus aus der mobilen App erforderlich ist, oder ist es besser, in ein natives WebSocket-Plugin zu investieren, um bei `https` zu bleiben? ### 2. Ein HTTP-Client, der seine URL einfror `HttpClient` fing `config.localApiUrl` in seinem Konstruktor ein — ausgeführt beim Laden des Moduls, also **bevor** das mobile Profil aufgelöst wurde. In der WebView ist `window.location.origin` gleich `https://localhost`, also die App selbst: Alle Anfragen wären ins Leere gegangen. Es ist jetzt ein Getter, der die Konfiguration bei jeder Anfrage liest. Im Web ändert sich der Wert nie, also identisches Verhalten. ### 3. Fehlendes `viewport-fit=cover` Die obere Leiste der App ging unter der Android-Uhr und den Benachrichtigungssymbolen verloren. Die Ursache war nicht der Header, sondern das ``: seiMit `viewport-fit=cover` sind alle Variablen `env(safe-area-inset-*)` gleich null. Interessanter Punkt: Die Frontend-Gladys verwendet bereits `safe-area-inset-bottom` an fünf Stellen (Chat, Dashboard, Geräteliste). Sie hatten also auf mobilen Geräten keine Wirkung. Der Fix aktiviert sie alle. * * * ## Validierung auf Gerät Getestet auf einem Xiaomi unter **Android 16** (WebView Chromium 151) gegen eine echte Instanz: | Punkt | Ergebnis | | --- | --- | | Web Crypto (RSA-OAEP 2048, ECDSA P-256, AES-GCM, PBKDF2) | 9/9 im `https`-Kontext | | WebSocket zu einer HTTP-Instanz | Handshake in 44 ms | | MSE / hls.js (Kameras) | Verfügbar | | Vollständiger Ablauf: Konfiguration, Login, Dashboards, Kameras | Funktionell | Eine gegenintuitive Messung: **PBKDF2 100.000 Iterationen in 15 ms auf dem Telefon, gegenüber 45 ms auf meinem PC**. Die Android-Implementierung ist hardwarebeschleunigt. Das von mir antizipierte Risiko einer langsamen Entsperrung auf mobilen Geräten existiert nicht. Eine weitere Lehre: Mein anfänglicher Validierungsprototype gab drei grüne Lichter, hat aber **keine** der beiden echten Blockaden erkannt. Er testete ein WebSocket von einer Seite `http://localhost` — also ohne Mixed Content — und stellte keine API-Anfrage. Man muss Crypto, WebSocket und eine echte API-Anfrage **in der endgültigen Schemakonfiguration** validieren, nicht isoliert. * * * ## Was noch zu tun ist **Los 2 — Touch-Ergonomie** : Niedrige Tab-Leiste, Android-Rückgesten, Finger-Ziehen-und-Ablegen des Dashboards, Verhalten der Tastatur. **Los 3 — Benachrichtigungen und Präsenz.** Dies ist der Hauptbeitrag der App im Vergleich zum Browser und der einzige Los, der Entwicklung auf Serverseite erfordert: eine Route zur Registrierung von Push-Token und eine Szenenaktion `user.send-push-notification`. Ein Punkt, der kollektiv entschieden werden muss: Eine selbstgehostete Instanz kann nicht direkt mit FCM oder APNs kommunizieren, mangels Dienstschlüsseln — die man natürlich nicht in einem öffentlichen Image verteilen kann. Der Relay über Gladys Plus ist der natürliche Weg (Inhalt wird Ende-zu-Ende verschlüsselt, die Benachrichtigung trägt nur einen Auslöser), mit einem Fallback auf lokale Benachrichtigungen ohne Abonnement. **Ist dies ein akzeptabler Kompromiss für die Community?** **Los 4 — Systemintegration** : mDNS-Entdeckung (der Server veröffentlicht bereits den Dienst), Startbildschirm-Widgets, iOS-App-Intents und Android-Shortcuts, Sprachassistent. **Los 5 — Veröffentlichung** : CI für Build und Signatur, Store-Einträge, Beta. * * * ## Zwei offene Punkte, bei denen ich Hilfe benötige **iOS konnte nicht validiert werden** : Ich habe keinen Mac. Vier Unbekannte bleiben — gesicherter Kontext auf `capacitor://`, MSE in WKWebView, Multicast-Entitlement für mDNS (von Apple fallweise genehmigt, mit unvorhersehbaren Verzögerungen) und das Verhalten von ATS gegenüber einer HTTP-Instanz. **Wenn jemand einen Mac und eine halbe Stunde Zeit hat** , das Validierungsprototype laufen zu lassen, würde dies diese vier Punkte auf einmal klären. **Die Frage des lokalen HTTPS.** Sie beeinflusst die Nutzung von Gladys Plus aus der App. Die Forderung nach einer HTTPS-Instanz ist technisch sauber, fügt aber eine Konfigurationsstufe für Benutzer hinzu, die dies heute nicht benötigen. Ich bin an euren Meinungen interessiert. * * * Die **vollständige Spezifikation ist im Anhang unten** (falten Sie den Abschnitt auf): Architektur, Verbindung, native Fähigkeiten, Sicherheit, harte Punkte, Lieferlose, Build und Abnahme. Der Code befindet sich in einem dedizierten Branch. Zögern Sie nicht, die Architekturentscheidung zu hinterfragen — genau jetzt ist es noch einfach, sie zu ändern. Vielen Dank fürs Lesen. * * * [details=« 📄 Vollständige technische Spezifikation (aufklappen) »] **Technische Spezifikation — v1** Die bestehende Gladys-Frontend (Preact / Vite) in eine native Android- und iOS-App über Capacitor portieren, mit voller Funktionsparität und den Fähigkeiten, die nur eine native App bieten kann: Push-Benachrichtigungen, Hintergrund-Geo-Lokalisierung, biometrische Entsperrung, Instanzentdeckung im lokalen Netzwerk. | | | | --- | --- | | **Codebasis** | Gladys 5.0.2 | | **Ansatz** | Capacitor + bestehende Frontend | | **Ziele** | Android 8+ · iOS 15+ | | **Umfang v1** | Volle Parität | | **Datum** | 30. August 2026 | * * * ### Inhaltsverzeichnis 1. Kontext und Ziele 2. Ist-Zustand 3. Zielarchitektur 4. Verbindung und Authentifizierung 5. Native Fähigkeiten 6. Schnittstellenanpassungen 7. Sicherheit 8. Identifizierte harte Punkte 9. Lieferlose 10. Build, CI und Veröffentlichung 11. Tests und Abnahme 12. Außerhalb des Umfangs der v1 * * * ### 1. Kontext und Ziele Gladys Assistant wird heute mobil über den Browser oder das Hinzufügen zum Startbildschirm genutzt. Dieser Ansatz stößt an seine Grenzen: keine zuverlässigen Benachrichtigungen, kein Hintergrund-Präsenz-Tracking, keine Präsenz in den Stores und ein Service Worker, der sich im aktuellen Zustand des Repositories bei jeder Aktivierung absichtlich deinstalliert. #### Ziele - **Funktionsparität** mit dem Web-Frontend: Dashboard, Geräte, Szenen, Kameras, Chat, Kalender, Karte, Einstellungen und Integrationen. - **Echte Push-Benachrichtigungen** , die von Gladys-Szenen ausgelöst werden, mit schnellen Aktionen aus der Benachrichtigung. - **Automatische Präsenz** durch Hintergrund-Geo-Lokalisierung, die die Gladys-Zonen-Erkennung speist. - **Reibungslose Verbindung** : Automatische Instanzentdeckung im lokalen Netzwerk, transparentes Umschalten lokal ↔ Gladys Plus. - **Eine einzige Codebasis** für Web, Android und iOS: Jede Frontend-Änderung profitiert allen drei Zielen ohne Portierung. #### Leitprinzipien - **Der Respekt vor der Privatsphäre bleibt die Regel.** Keine Telemetrie, keine Drittanbieter-Analytik-SDKs. Die Ende-zu-Ende-Verschlüsselung von Gladys Plus wird ohne Ausnahme beibehalten. - **Das Frontend bleibt die einzige Wahrheit.** Die native Hülle enthält keine Geschäftslogik: Sie bietet Fähigkeiten, das Frontend nutzt sie. - **Saubere Abwärtskompatibilität.** Jede native Funktion ist optional; ihr Fehlen (abgelehnte Berechtigung, nicht kompatible Plattform) bricht die App nie. * * * ### 2. Ist-Zustand Das Frontend ist eine Preact 10-Anwendung, die von Vite 6 gebaut wird, mit `preact-router` für die Routing, `unistore` für den globalen Zustand und `preact-i18n` für die Internationalisierung in drei Sprachen (fr, en, de). Sie wird entweder vom lokalen Gladys-Server (`server/static`) oder von Gladys Plus bereitgestellt. #### Was direkt wiederverwendet werden kann | Element | Standort | Status | | --- | --- | --- | | Bildschirme und Routing | `front/src/routes/` | Unverändert | | Dashboard-Widgets (22 Typen) | `front/src/components/boxs/` | Unverändert | | Aktionen und `unistore` | `front/src/actions/` | Unverändert | | Übersetzungen fr / en / de | `front/src/config/i18n/` | Unverändert | | Thema und dunkler Modus | `front/src/style/` | Unverändert | #### Was angepasst werden muss | Element | Standort | Art der Arbeit | | --- | --- | --- | | URL-Konfiguration | `front/src/config.js` | Die URLs sind zum Zeitpunkt des `vite build` über `process.env` festgelegt. Sie müssen zur Laufzeit dynamisch gemacht werden. **Harter Punkt** | | Sitzungsspeicher | `front/src/utils/Session.js`, `front/src/utils/keyValueStore.js` | `localStorage` im Klartext. Muss durch einen verschlüsselten Speicher ersetzt werden, der an den Keychain / Keystore angebunden ist. **Harter Punkt** | | HTTP-Client | `front/src/utils/HttpClient.js` | ✅ **Erledigt (Los 1).** `localApiUrl` wurde im Konstruktor erfasst, ausgeführt beim Laden des Moduls über `getDefaultState()` — also vor der Auflösung des mobilen Profils. Jetzt ein Getter, der die Konfiguration bei jeder Anfrage liest. Im Web ändert sich der Wert nie: identisches Verhalten. | | Sichere Bereiche | `front/index.html`, `front/src/template.html` | ✅ **Erledigt (Los 1).** Das `` nEs fehlte `viewport-fit=cover`, wodurch **alle** Variablen `env(safe-area-inset-*)` auf null gesetzt wurden — einschließlich der fünf vorhandenen Verwendungen von `safe-area-inset-bottom`. | | WebSocket | `front/src/utils/Session.js` | Wird alle 1 Sekunde ohne Berücksichtigung des Anwendungslebenszyklus neu verbunden. Es sollte eine Backoff-Strategie und eine Reaktion auf Schlafereignisse hinzugefügt werden. | | Service Worker | `front/old-sw.js` | Deinstalliert sich selbst bei der Aktivierung. Wird nicht in der nativen Shell verwendet; sollte für das Web beibehalten werden, um alte Caches zu bereinigen. | | Kameras (HLS) | `front/src/components/boxs/camera/` | Benutzerdefinierter `hls.js`-Lader zum Einfügen des Tokens. Muss in der WebView validiert werden, insbesondere das native HLS auf iOS. | | Drag-and-Drop | `front/src/utils/dragAndDropBackend.js` | Wechselt bereits zwischen HTML5- und Touch-Backends; muss in der WebView neu validiert werden. | #### Serverseitig Für die Lose 1 und 2 sind keine Änderungen erforderlich: Die REST-API (`server/api/controllers/`, 25 Controller) und das WebSocket decken bereits die Anforderungen. Zwei Servererweiterungen sind später erforderlich: die Registrierung der Push-Tokens (Los 3) und die entsprechende Szenenaktion. * * * ### 3. Zielarchitektur Die Frontend wird genau wie heute kompiliert und dann mit Capacitor in eine native WebView verpackt. Die Fähigkeiten, die das Web nicht bieten kann, werden dem Frontend in Form von Capacitor-Plugins hinter einer Abstraktionsschicht bereitgestellt, die neutrale Werte zurückgibt, wenn die App in einem Browser läuft. ```auto ┌─────────────────────────────────────┐ │ MOBILE APPLIKATION │ │ │ ┌──────────────────────────────┐ │ ┌───────────────────────────────┐ │ │ Lokales Netzwerk │ │ │ WebView — front Preact │ │───────>│ REST /api/v1 + WebSocket │ │ │ routes/ · components/ │ │ │ Trägertoken, minimale Latenz │ │ │ ───────────────────────────── │ │ │ mDNS-Entdeckung │ │ │ utils/native/ — Abstraktion │ │ └──────────────┬───────────────┘ │ │ no-op im Web │ │ │ │ └───────────────┬───────────────┘ │ ┌──────────────▼───────────────┐ │ ▼ │ │ Gladys Plus — Remote │ │ ┌───────────────────────────────┐ │───────>│ gladys-gateway-js │ │ │ Natives Capacitor-Shell │ │ │ RSA + ECDSA, Ende-zu-Ende │ │ │ push · Geolokation · Biometrie│ │ │ Der Server entschlüsselt nichts│ │ │ mDNS · Speicher · Widgets │ │ └──────────────┬───────────────┘ │ └───────┬───────────────┬───────┘ │ │ └──────────┼───────────────┼──────────┘ │ ▼ ▼ ┌──────────────▼───────────────┐ ┌────────────┐ ┌────────────┐ │ Gladys-Instanz │ │ Android │ │ iOS │ │ Node 24 · SQLite │ │ Kotlin·FCM │ │ Swift·APNs │ │ 39 Dienste │ └────────────┘ └────────────┘ └──────────────────────────────┘ ``` Die Auswahl des Netzwerkpfads erfolgt automatisch und wird bei jedem Netzwerkwechsel neu bewertet; der Benutzer kann sie über die Einstellungen erzwingen. Das kompilierte Frontend ist identisch mit dem, das im Web bereitgestellt wird: Nur die Schicht `utils/native/` wird hinzugefügt und gibt außerhalb von mobilen Geräten neutrale Implementierungen zurück. #### Verzeichnisstruktur Ein neues Verzeichnis `mobile/` an der Wurzel, neben `front/` und `server/`: ```auto mobile/ ├── capacitor.config.ts Konfiguration, verweist auf front/build ├── package.json Nur Capacitor-Abhängigkeiten ├── android/ Generiertes Android-Projekt, versioniert ├── ios/ Generiertes Xcode-Projekt, versioniert ├── plugins/ Eigenen Plugins (mDNS, Entdeckung) └── resources/ Quellen für Icons und Startbildschirme front/src/utils/native/ Abstraktionsschicht, im Frontend ├── index.js Plattformerkennung ├── push.js ├── geolocation.js ├── biometrics.js ├── secureStorage.js └── discovery.js ``` #### Ausgewählte Plugins | Bedarf | Plugin | Herkunft | | --- | --- | --- | | Push-Benachrichtigungen | `@capacitor/push-notifications` | Offiziell | | Lokale Benachrichtigungen | `@capacitor/local-notifications` | Offiziell | | Geolokalisierung (einmalig) | `@capacitor/geolocation` | Offiziell | | Geolokalisierung (Hintergrund) | `@capacitor-community/background-geolocation` | Community | | Verschlüsselter Speicher | `capacitor-secure-storage-plugin` | Community | | Biometrie | `@aparajita/capacitor-biometric-auth` | Community | | Netzwerkstatus | `@capacitor/network` | Offiziell | | App-Lebenszyklus | `@capacitor/app` | Offiziell | | Statusleiste und Kerben | `@capacitor/status-bar` | Offiziell | | mDNS-Erkennung | `gladys-discovery` | **Zu schreiben** | > **Designentscheidung** — Jedes Community-Plugin birgt ein Wartungsrisiko. Die Schicht `utils/native/` existiert genau dafür, dass der Ersatz eines veralteten Plugins nur eine einzige Datei betrifft, niemals die Bildschirme. * * * ### 4. Verbindung und Authentifizierung Dies ist der strukturierendste Teil der Spezifikation. Die aktuelle Frontend-Anwendung kennt nur einen Modus gleichzeitig, der zum Zeitpunkt des Builds durch die Variable `GATEWAY_MODE` festgelegt wird. Die mobile App muss beide gleichzeitig verwalten und ohne Benutzereingriff zwischen ihnen wechseln. #### 4.1 Laufzeitkonfiguration `front/src/config.js` liest `process.env`, das Vite zum Zeitpunkt des Builds durch Literale ersetzt. Es muss eine Laufzeitauflösung eingeführt werden: - Im Web bleibt das aktuelle Verhalten unverändert: keine Rückschritte. - Auf mobilen Geräten stammen die URLs vom aktiven Verbindungsprofil, das im verschlüsselten Speicher gespeichert ist. Konkrekt stellt `config.js` ein veränderliches Objekt bereit, das beim Start durch `utils/native/` gefüllt wird, bevor die erste Darstellung erfolgt. Die Module, die die Konfiguration heute importieren, bleiben unverändert. #### 4.2 Verbindungsprofile Die App verwaltet mehrere Profile — ein Hauptzuhause, ein Zweitwohnsitz, eine Testinstanz. Jedes Profil speichert: | Feld | Inhalt | | --- | --- | | `id` | Lokale UUID | | `name` | Angezeigter Name, vom Benutzer eingegeben | | `mode` | `local`, `gateway` oder `auto` | | `localUrl` | URL der Instanz im lokalen Netzwerk | | `localFingerprint` | Fingerabdruck des Zertifikats, falls selbstsigniertes HTTPS | | `ssids` | WLAN-Netzwerke, in denen der lokale Modus gilt | | `credentials` | Referenz zum verschlüsselten Speicher, niemals der Wert | #### 4.2 bis Die drei URLs von Gladys Plus Nicht zu verwechseln — sie haben unterschiedliche Rollen: | URL | Rolle | Verwendet von | | --- | --- | --- | | `https://api.gladysgateway.com` | **Die API** des Gateways | `config.gladysGatewayApiUrl`, aufgerufen von `gladys-gateway-js` | | `https://plus.gladysassistant.com` | **Das Web-Frontend** von Gladys Plus (derselbe Code, im Gateway-Modus) | Ausgehende Links: Abonnement, Abrechnung | | `https://gladysassistant.com/plus/` | Marketing-Seite | `utils/gladysPlusUrl.js` (Anmelde-Links) | Die mobile App kommuniziert mit der **API** , niemals mit dem gehosteten Frontend: sie _ist_ das Frontend. Der Standardwert von `config.js` ist daher bereits korrekt und muss nicht geändert werden. Andererseits müssen die Abläufe, die nicht in der App ablaufen können — Abonnementverwaltung, Stripe-Abrechnung — `plus.gladysassistant.com` im Systembrowser öffnen und nicht in der WebView: ein Zahlungstunnel in einer Anwendungs-WebView wird von beiden Stores abgelehnt. Das Plugin `@capacitor/browser` (System-Tab) ist das richtige Fahrzeug. #### 4.3 Erkennung der lokalen Instanz Der Gladys-Server veröffentlicht bereits einen mDNS-Dienst (`server/lib/mdns/`). Das zu schreibende Plugin `gladys-discovery` fragt diesen Dienst ab und zeigt die gefundenen Instanzen an: - **Android** : `NsdManager`, mit Erwerb eines `MulticastLock` während der Suche. - **iOS** : `NWBrowser` (Network-Framework). Erfordert das Entitlement `com.apple.developer.networking.multicast`, das explizit bei Apple angefordert werden muss, und die Deklaration `NSBonjourServices` in `Info.plist`. Falls die Erkennung fehlschlägt, bleibt die manuelle Eingabe einer Adresse immer möglich: sie ist niemals ein versteckter Ausweichweg, sondern eine Option, die bereits auf dem ersten Bildschirm sichtbar ist. #### 4.4 Wechsel lokal ↔ entfernt Im Modus `auto` wählt die App den Netzwerkpfad bei jedem Start, bei jeder Rückkehr in den Vordergrund und bei jeder von `@capacitor/network` gemeldeten Verbindungsänderung: 1. Wenn ein lokales Profil konfiguriert ist, wird ein `GET /api/v1/ping` mit einer Schutzverzögerung von 1,5 Sekunden versucht. 2. Bei Erfolg wird der lokale Modus beibehalten: minimale Latenz, keine externe Abhängigkeit. 3. Bei Fehlschlag und wenn ein Gladys Plus-Konto verknüpft ist, wechselt die App zum Gateway. 4. Wenn kein Pfad antwortet, wird ein Offline-Bildschirm mit den letzten bekannten Daten und einem Wiederaufnahme-Button angezeigt. Der Wechsel **rekonstruiert** den HTTP-Client und die WebSocket-Verbindung. Er wird diskret in der Benutzeroberfläche angezeigt (ein Indikator in der Kopfzeile), niemals durch ein blockierendes Dialogfeld. > **Achtung** — Die beiden Modi verwenden nicht denselben Token-Speicher noch denselben Client: `Session` + `HttpClient` für lokal, `GatewaySession` + `GatewayHttpClient` für Gladys Plus. Der Wechsel muss die Caches der fliegenden Anfragen von `HttpClient` (die `Map` `pendingRequests`) leeren, um zu verhindern, dass eine Antwort aus dem alten Pfad dem neuen zugeordnet wird. #### 4.5 End-to-End-Verschlüsselung `GatewaySession` stützt sich auf `@gladysassistant/gladys-gateway-js`, das `window.crypto` erhält. In einer WebView ist die Web Crypto API nur in einem sicheren Kontext verfügbar: die Schemata `capacitor://` (iOS) und `https://` (Android) sind dies, im Gegensatz zu `http://`. Dieser Punkt muss bereits im ersten Los validiert werden, da er den gesamten Fernzugriff bedingt. Die serialisierten Schlüssel (`gateway_serialized_keys`) befinden sich heute in `localStorage`. Auf mobilen Geräten gehen sie in den verschlüsselten Speicher, der an den Keychain (iOS) oder den Keystore mit Hardware-Verschlüsselung (Android) angelehnt ist. #### 4.6 Zwei-Faktor-Authentifizierung Der bestehende 2FA-Ablauf (`actions/login/loginGateway.js`) bleibt unverändert, einschließlich der Generierung der Wiederherstellungscodes und des Einfügens aus der Zwischenablage. Ein automatisches Ausfüllen des Codes aus den Tastaturvorschlägen wird über das Attribut `autocomplete="one-time-code"` hinzugefügt. #### 4.7 Biometrische Sperre Optional, aktivierbar in den Einstellungen. Wenn es aktiviert ist, wird beim Start und nach einer konfigurierbaren Inaktivitätsdauer (standardmäßig 5 Minuten im Hintergrund) eine Entsperrung per Fingerabdruck oder Gesichtserkennung angefordert. Die Ausweichmöglichkeit ist der Gerätecode; es gibt niemals einen eigenen Gladys-Code, den man zusätzlich merken muss. * * * ### 5. Native Fähigkeiten #### 5.1 Push-Benachrichtigungen Dies ist der Hauptbeitrag der App im Vergleich zum Web. Er erfordert eine Entwicklung auf der Gladys-Server-Seite und nicht nur auf der mobilen Seite. **Registrierung.** Beim ersten Start nach Akzeptanz der Berechtigung erhält die App ein FCM-Token (Android) oder APNs-Token (iOS) und sendet es an die Instanz. Neue Route zu erstellen: `POST /api/v1/user/push_token`, mit dem Token, der Plattform und der Sitzungs-ID. Das Token ist mit der bestehenden Sitzung verknüpft: Das Widerrufen einer Sitzung widerruft auch den zugehörigen Push. **Versand.** Eine selbstgehostete Gladys-Instanz kann nicht direkt mit FCM oder APNs kommunizieren, ohne Dienstschlüssel — die nicht in einem öffentlichen Image verteilt werden können. Zwei Wege: - **Über Gladys Plus (empfohlen)** — Die Instanz überträgt die Benachrichtigung an das Gateway, das die Schlüssel besitzt und an FCM / APNs weiterleitet. Der nützliche Inhalt ist Ende-zu-Ende verschlüsselt; die transportierte Benachrichtigung enthält nur einen Auslöser, die App holt den eigentlichen Inhalt von der Instanz beim Empfang ab. - **Ohne Gladys Plus** — Ausweichen auf lokale Benachrichtigungen: Solange die WebSocket-Verbindung aktiv ist, plant die App selbst eine Benachrichtigung. Funktioniert im kürzlichen Hintergrund, nicht nach einem längeren Ruhezustand. Diese Einschränkung muss in den Einstellungen klar angekündigt werden, nicht erst beim Gebrauch entdeckt. **Auslösung von einer Szene.** Eine neue Szenenaktion `user.send-push-notification` wird hinzugefügt, mit Empfängern, Titel, Nachricht und optional einem Kamerabild. Sie muss zwingend im Joi-Schema von `server/models/scene.js` deklariert werden, andernfalls schlägt die Szenenregistrierung mit einem 422-Fehler ohne explizite Nachricht fehl. **Schnellaktionen.** Die Benachrichtigungen enthalten bis zu drei Aktionsbuttons, die in der Szene definiert sind: Ausführung einer anderen Szene, Ein- oder Ausschalten eines Geräts, Öffnen einer Kamera. Diese Aktionen werden ohne Öffnen der App durchgeführt, wenn das Netzwerk es zulässt. #### 5.2 Geolokalisierung und Anwesenheit Gladys verfügt bereits über `server/lib/location/` und die Verwaltung von Zonen. Die App versorgt `POST /api/v1/location`: - **Zonenbasierte Verfolgung** anstelle kontinuierlicher Verfolgung: Die App abonniert Ein- und Ausgänge der in Gladys definierten Zonen. Der Akkuverbrauch ist deutlich geringer als bei periodischen Abfragen. - **Reduzierte Genauigkeit** standardmäßig: Die Position wird nur beim Passieren einer Zone übertragen, nicht kontinuierlich. - **Offline-Warteschlange:** Ereignisse, die ohne Netzwerk erfasst wurden, werden lokal gespeichert und bei der Wiederverbindung mit dem tatsächlichen Zeitstempel gesendet. - **Globaler Schalter** , sichtbar in den Einstellungen, und sofortige Beendigung der Verfolgung, wenn er ausgeschaltet wird. > **Store-Beschränkung** — Die Hintergrund-Geolokalisierung ist der häufigste Ablehnungsgrund im App Store. Es wird benötigt: eine klare Erklärung vor der Berechtigungsanfrage, eine präzise Begründung in `NSLocationAlwaysAndWhenInUseUsageDescription` und eine voll funktionsfähige App, wenn die Berechtigung verweigert wird. Auf Android 13+ wird die Berechtigung `ACCESS_BACKGROUND_LOCATION` in einem zweiten Schritt nach der Vordergrundberechtigung angefordert. #### 5.3 Widgets für den Startbildschirm Nativ geschrieben: WidgetKit in SwiftUI auf iOS, Glance auf Android. Sie lesen einen von der App in einem gemeinsamen Speicherbereich (App Group auf iOS, `SharedPreferences` auf Android) geschriebenen Datenschnappschuss, der bei jedem Wechsel in den Vordergrund und bei jeder Benachrichtigung aktualisiert wird. - **Szenen:** Bis zu vier favorisierte Szenen, die mit einem Tastendruck ausgeführt werden können. - **Temperatur:** Temperatur eines ausgewählten Raums. - **Geräte:** Zustand und Umschaltung von zwei bis vier Geräten. Die Widgets öffnen keine eigene Sitzung: Sie delegieren an die App, die die Aktion ausführt. Wenn die Sitzung abgelaufen ist, zeigt das Widget einen Zustand der erforderlichen Wiederverbindung an, anstatt einen Fehler. #### 5.4 Systemverknüpfungen - **iOS:** Szenen werden in App Intents exponiert, wodurch sie in Kurzinfo, Siri und der Aktionsschaltfläche verfügbar sind. - **Android:** Dynamische Verknüpfungen auf dem App-Symbol für favorisierte Szenen. #### 5.5 Sprachassistent Die Frontend-Schnittstelle verfügt bereits über eine vollständige Sprachkette: `speechCommandRecorder.js`, `recordUntilSilence.js`, `speechTtsPlayback.js`, gestützt auf `gateway.stt.js` und `gateway.processVoiceMessage.js` auf Serverseite. In der WebView erfordert der Mikrofonzugriff die native Berechtigung (`NSMicrophoneUsageDescription`, `RECORD_AUDIO`) _und_ die Erlaubnis auf WebView-Ebene. Auf Android erfolgt Letzteres über `onPermissionRequest`, das im nativen Shell behandelt werden muss. Die TTS-Wiedergabe muss die Audio-Sitzungskategorie auf iOS konfigurieren, um nicht durch den Stummschaltmodus unterbrochen zu werden. #### 5.6 Kameras Der HLS-Stream wird über `hls.js` mit einem benutzerdefinierten Lader gelesen, der das Authentifizierungstoken injiziert. In der WebView: - Auf iOS wird der native HLS-Player von `