# Firebase/FCM einrichten – Howto Dieses Dokument beschreibt die praktischen Schritte, um die im Code vorbereiteten FCM-Aufwachsignale für die mobilen PWA-Ansichten zu aktivieren. FCM überträgt ausschließlich das Signal; Nachrichten und Positionen laufen weiterhin über WebSocket und die Broker-Queue. Die Architektur und die Plattformgrenzen stehen in [`FCM_ARCHITEKTUR.md`](FCM_ARCHITEKTUR.md). ## Voraussetzungen - Ein Google-Konto und Zugriff auf die [Firebase Console](https://console.firebase.google.com/). - Die CMBNet-Installation läuft über **HTTPS** (auch im Test). Web Push und Service Worker funktionieren nicht über eine reine HTTP-Adresse, außer auf `localhost`. - Die mobile Ansicht ist als PWA installiert (zum Home-Bildschirm hinzugefügt). Besonders auf iOS/iPadOS ist das Voraussetzung für Web Push. - Python-Umgebung der Anwendung kann Pakete installieren. ## 1. Firebase-Projekt anlegen 1. In der Firebase Console **Projekt hinzufügen** wählen. 2. Projektnamen vergeben (z. B. `cmbnet-push`) und die Analytics-Option nach Bedarf aktivieren. Für FCM ist Analytics nicht erforderlich. 3. Nach dem Anlegen die Projekt-ID notieren. Sie wird später als `CMBNET_FCM_PROJECT_ID` bzw. `CMBNET_FCM_WEB_PROJECT_ID` verwendet. ## 2. Web-App registrieren 1. In den **Projekteinstellungen → Allgemein** unter *Meine Apps* die Plattform **Web** (``) hinzufügen. 2. Einen Spitznamen vergeben und die App registrieren. 3. Den angezeigten `firebaseConfig`-Block notieren. Er enthält ausschließlich öffentliche Werte: ```js { apiKey: "...", authDomain: "cmbnet-push.firebaseapp.com", projectId: "cmbnet-push", storageBucket: "cmbnet-push.appspot.com", messagingSenderId: "...", appId: "..." } ``` Diese Werte sind **keine Geheimnisse** und werden vom Server an Browser und Service Worker ausgeliefert. Der Service-Account aus Schritt 4 darf dagegen niemals in eine Webseite oder in das Repository gelangen. ## 3. Cloud Messaging und VAPID-Schlüssel 1. In der Firebase Console unter **Cloud Messaging** die Web-Push- Konfiguration öffnen. 2. Falls noch kein Schlüsselpaar existiert, unter *Web-Push-Zertifikate* ein Schlüsselpaar erzeugen. 3. Den angezeigten **VAPID-Schlüssel** (öffentlicher Schlüssel) notieren. Er wird als `CMBNET_FCM_VAPID_KEY` benötigt. 4. Die Web-Push-Konfiguration muss zum selben Firebase-Projekt wie die Web-App gehören. ## 4. Service-Account für den Server erzeugen 1. In der Firebase Console **Projekteinstellungen → Dienstkonten** öffnen. 2. **Neuen privaten Schlüssel generieren** wählen und die JSON-Datei herunterladen. 3. Die Datei außerhalb des Repositories ablegen, z. B. `/etc/cmbnet/firebase-service-account.json`, und nur für den Anwendungsbenutzer lesbar machen: ```bash sudo install -m 600 firebase-service-account.json \ /etc/cmbnet/firebase-service-account.json ``` 4. Alternativ kann der JSON-Inhalt als eine Zeile in `CMBNET_FCM_SERVICE_ACCOUNT_JSON` gesetzt werden. Für den Dauerbetrieb ist eine Datei mit restriktiven Rechten vorzuziehen, weil Umgebungsvariablen leichter in Prozesslisten oder Logs auftauchen. ## 5. Python-Abhängigkeit installieren FCM nutzt das optionale Paket `firebase-admin`. Es ist in `requirements.txt` eingetragen, muss aber in der aktiven Umgebung installiert sein: ```bash cd CMBNet source .venv/bin/activate pip install -r requirements.txt ``` Ohne dieses Paket startet die Anwendung weiterhin; FCM bleibt dann deaktiviert und protokolliert einen entsprechenden Hinweis. ## 6. Umgebungsvariablen setzen Die Anwendung liest die Konfiguration aus Umgebungsvariablen (siehe `config.py`). Ein vollständiges Beispiel für einen Dienstmanager oder eine `.env`-Datei: ```bash CMBNET_FCM_ENABLED=1 # Serverseitiger Versand CMBNET_FCM_PROJECT_ID=cmbnet-push CMBNET_FCM_SERVICE_ACCOUNT_FILE=/etc/cmbnet/firebase-service-account.json # Alternativ statt der Datei: # CMBNET_FCM_SERVICE_ACCOUNT_JSON={"type":"service_account",...} # Öffentliche Web-Konfiguration aus Schritt 2 CMBNET_FCM_WEB_API_KEY=... CMBNET_FCM_WEB_AUTH_DOMAIN=cmbnet-push.firebaseapp.com CMBNET_FCM_WEB_PROJECT_ID=cmbnet-push CMBNET_FCM_WEB_STORAGE_BUCKET=cmbnet-push.appspot.com CMBNET_FCM_WEB_MESSAGING_SENDER_ID=... CMBNET_FCM_WEB_APP_ID=... # Web-Push aus Schritt 3 CMBNET_FCM_VAPID_KEY=... # Optional: Zeitverhalten CMBNET_FCM_OFFLINE_WAKE_MINUTES=5 CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS=60 CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS=30 ``` Die Datei mit den Umgebungsvariablen muss dieselben Rechte wie die Service-Account-Datei besitzen. Nach Änderungen den WSGI-Prozess neu starten; Python liest die Werte beim Start. ### Prüfen, ob die Konfiguration vollständig ist `public_fcm_config()` aktiviert FCM nur, wenn `CMBNET_FCM_ENABLED` gesetzt ist **und** API-Key, Projekt-ID, Sender-ID, App-ID und VAPID-Schlüssel vorhanden sind. Prüfen lässt sich das über die vom Server erzeugte Datei: ```bash curl -s https://example.com/fcm-sw-config.js ``` Erwartet wird ein JavaScript-Objekt mit `"enabled": true` und gefüllten `firebase`-Werten. Bei `"enabled": false` fehlt mindestens einer der oben genannten Werte oder `firebase-admin` ist nicht installiert. ## 7. Datenbankmigration Beim nächsten Start führt `ensure_schema()` die idempotenten Migrationen aus. Neu sind die Spalten `ws_clients.client_type`, `ws_clients.last_wake_at`, `ws_clients.last_wake_reason` sowie die Tabelle `ws_push_tokens`. Eine manuelle Migration ist nicht nötig; ein Backup der SQLite-Datei vor dem ersten Start ist trotzdem empfehlenswert. ## 8. Mobile PWA installieren und Benachrichtigungen erlauben 1. Die mobile Ansicht (Gruppen-View bzw. mobiler Dispatcher) über HTTPS öffnen. 2. Im Browsermenü **Zum Home-Bildschirm** bzw. **App installieren** wählen. 3. Die PWA aus dem Home-Bildschirm starten. 4. In den Einstellungen der mobilen Ansicht **Benachrichtigungen aktivieren** antippen und die Browserabfrage bestätigen. 5. Danach lädt die Seite das Firebase-SDK, fordert ein FCM-Token an und registriert es über `POST //api/push/register`. Der Client-Typ (`group_view` bzw. `dispatcher_mobile`) wird dabei gegen die Rolle geprüft. Auf iOS/iPadOS muss die App wirklich installiert sein; in einem normalen Safari-Tab wird kein Token registriert. Nach dem Entfernen der PWA vom Home-Bildschirm oder dem Entziehen der Benachrichtigungserlaubnis endet die Zustellung. ## 9. Funktion testen ### Token-Registrierung prüfen Nach dem Aktivieren der Benachrichtigungen in der Datenbank nachsehen: ```bash sqlite3 instance/cmbnet.sqlite3 \ "SELECT tenant_id, client_id, account_id, client_type, platform, auto_position, invalid FROM ws_push_tokens;" ``` Es muss ein Eintrag für den mobilen Client vorhanden sein. Ein leeres Ergebnis bedeutet meist: keine HTTPS-Verbindung, keine installierte PWA, keine Benachrichtigungserlaubnis oder `enabled: false` in `fcm-sw-config.js`. ### Manuellen Wake auslösen Im Desktop-Dispatcher oder im mobilen Dispatcher den Radar-Button antippen. Der Button ruft `POST //api/push/wake` auf. Die Antwort enthält `candidates`, `sent` und `failed`. - `sent > 0`: FCM hat das Signal angenommen. - `candidates = 0`: kein getrennter mobiler Client mit gültigem Token. - HTTP 503: FCM ist nicht vollständig konfiguriert. - HTTP 403: Rolle darf nicht wecken (nur Dispatcher/Administrator). Da nur getrennte Clients geweckt werden, muss die mobile PWA vor dem Test geschlossen oder die WebSocket-Verbindung unterbrochen sein. ### Offline-Timeout prüfen `CMBNET_FCM_OFFLINE_WAKE_MINUTES` testweise auf `1` setzen, PWA schließen und nach ein bis zwei Minuten den Radar-Button im Desktop-Dispatcher verwenden. Bei aktiver automatischer Positionsübertragung sollte die Gruppen-View nach dem Wake eine neue Position senden. Der Service Worker zeigt nur dann eine Benachrichtigung, wenn kein PWA-Fenster erreichbar ist. ### FCM-Versand direkt prüfen Bei aktiviertem Debug-Logging des WSGI-Servers erscheinen Warnungen, wenn `firebase-admin` fehlt, die Initialisierung scheitert oder FCM einen Batch ablehnt. Ungültige Tokens werden als `invalid` markiert und nicht mehr verwendet. ## Troubleshooting | Symptom | Ursache / Lösung | | --- | --- | | `fcm-sw-config.js` liefert `enabled: false` | `CMBNET_FCM_ENABLED` nicht gesetzt oder einer der Web-Werte/VAPID fehlt. | | Kein Token in `ws_push_tokens` | PWA nicht installiert, keine Benachrichtigungserlaubnis, kein HTTPS oder Client-Typ/Rolle passt nicht. | | `firebase-admin ist nicht installiert` im Log | `pip install -r requirements.txt` in der aktiven Umgebung ausführen. | | `FCM-Initialisierung fehlgeschlagen` | Service-Account-Datei fehlt, ist nicht lesbar oder gehört zu einem anderen Projekt. | | `SENDER_ID_MISMATCH` bzw. Token wird ungültig | Web-Konfiguration und Service-Account stammen aus verschiedenen Firebase-Projekten. | | Radar-Button meldet 0 Kandidaten | Der Client ist noch verbunden, hat kein Token oder wurde bereits innerhalb des Cooldowns geweckt. | | iOS erhält keine Push-Nachricht | PWA nicht installiert, iOS < 16.4 oder Benachrichtigungen nicht erlaubt. | | Benachrichtigung erscheint, aber keine Position | Kein PWA-Fenster aktiv oder Standort im Hintergrund nicht erlaubt; die letzte bekannte Position wird verwendet. | | Doppelte Wakes bei mehreren Workern | `CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS` und `CMBNET_WS_BUS_POLL_INTERVAL` prüfen; die Reservierung erfolgt über `last_wake_at`. | ## Sicherheit und Datenschutz - Der Service-Account-Schlüssel bleibt auf dem Server und gehört nicht ins Repository, in Templates oder in Browser-JavaScript. - FCM-Tokens sind installationsbezogene Kennungen. Sie werden nicht geloggt und beim Abmelden über `DELETE //api/push/register` entfernt. - Das FCM-Signal enthält nur `type` und `reason`. Mandant, Rolle, Nachricht, Absender und Position werden nicht über Firebase übertragen. - Firebase ist ein externer Google-Dienst. Der Betrieb muss die daraus folgenden Datenschutz- und Verfügbarkeitsanforderungen bewerten. - Die PWA muss über HTTPS laufen; der Server sollte nur hinter dem Reverse-Proxy erreichbar sein.