12 KiB
FCM-Aufwachsignale für mobile PWA-Clients
Zweck
Mobile Webviews sollen gezielt aus dem Hintergrund geholt werden, damit sie ihre WebSocket-Verbindung erneuern, die persistente Broker-Queue leeren und – bei aktivierter Positionsübertragung – mindestens ein Positionsupdate senden. Google Firebase Cloud Messaging (FCM) transportiert dabei nur ein Signal. Chat-Nachrichten, Positionsdaten, Mandanten, Rollen und URLs der Anwendung bleiben ausschließlich in der WebSocket-Kommunikation bzw. in der Datenbank.
Das Signal besteht aus einem Data-Payload mit den Feldern type und reason
(z. B. queue, offline, manual). Diese Metadaten dienen nur der
Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist.
Sie sind kein Anwendungsinhalt.
Beteiligte Komponenten
| Komponente | Aufgabe |
|---|---|
cmbnet/ws/broker.py |
Erkennt nicht zustellbare Nachrichten, trennt Verbindungen ohne Lebenszeichen und fordert ein Wake-Signal an. |
cmbnet/ws/heartbeat.py |
Sendet Code-1-Pings und prüft, ob Clients noch antworten. |
cmbnet/ws/push.py |
Periodischer Worker für den Offline-Timeout. |
cmbnet/services/fcm_service.py |
Firebase-Admin-Initialisierung und FCM-Versand. |
cmbnet/api/push.py |
Token-Registrierung, Abmeldung und manueller Wake-Button. |
static/js/sw.js |
Empfängt das FCM-Signal, weckt ein Fenster und zeigt ggf. eine Benachrichtigung. |
static/js/views/mobile.js |
Registriert das Token, verbindet den WebSocket neu und sendet die Position. |
templates/dispatcher*.html |
Radar-Button zum manuellen Wecken. |
Ablauf
- Die mobile PWA fordert nach Erlaubnis für Benachrichtigungen ein
FCM-Token an. Das Token wird über
POST /<tenant>/api/push/registerzusammen mit Client-ID, Client-Typ und der Einstellungauto_positiongespeichert. - Der Broker puffert eine Nachricht für einen getrennten mobilen Client
wie bisher in
ws_client_queue. - Zusätzlich prüft er, ob ein gültiges FCM-Token vorliegt und ob der Client als getrennt gilt. Wenn ja, sendet er ein FCM-Aufwachsignal.
- Der Service Worker wird durch FCM geweckt. Er kann selbst keine
WebSocket-Verbindung betreiben. Deshalb übergibt er den Impuls per
postMessagean ein bereits geöffnetes PWA-Fenster. - Die PWA baut den WebSocket neu auf. Der Broker liefert die Queue und die Late Entries aus. Neue Nachrichten lösen wie bisher den In-App-Dialog aus.
- Bei aktivierter automatischer Positionsübertragung sendet die PWA mindestens eine Position. Zuerst wird eine frische Geolocation angefordert; schlägt das im Hintergrund fehl, wird die letzte bekannte Position verwendet.
- Der Service Worker wartet über einen
MessageChannelbis zu 20 Sekunden auf die Bestätigung der PWA. Erst danach beendet er den Push-Event. Ist kein Fenster erreichbar, zeigt er eine allgemeine Benachrichtigung an. - Ein Klick auf diese Benachrichtigung öffnet
/<prefix>/wake. Die Route leitet anhand der bestehenden Session in die passende mobile View. FCM selbst enthält keine Mandanten- oder Rollen-URL.
Trigger
Gequeuete Nachricht
Sobald eine Nachricht mit Code >= 99 für einen mobilen Client eingereiht
oder direkt an ihn gesendet wird, versucht der Broker ein FCM-Signal. Das gilt
bewusst auch dann, wenn der Client laut Broker noch als verbunden gilt: Auf
iOS bleibt dieser Status oft veraltet, obwohl der WebSocket nicht mehr
erreichbar ist. Mehrere Nachrichten innerhalb des Queue-Cooldowns lösen nur
ein Signal aus. Mit CMBNET_FCM_WAKE_CONNECTED_CLIENTS=0 lässt sich das
zusätzliche Wecken verbundener Clients abschalten.
Offline-Erkennung
Ein Client gilt nur dann als offline, wenn der Broker seine WebSocket-
Verbindung als beendet markiert hat (ws_clients.disconnected_at). Dafür gibt
es drei Wege:
- Ein sauber geschlossener Socket wird in der WS-Route unmittelbar erkannt.
- Die mobile View schließt ihren Socket beim Wechsel in den Hintergrund
(
visibilitychange) bzw. beim Verlassen der Seite (pagehide). Damit ist sie sofort offline, ohne auf einen Timeout warten zu müssen. Beim Sichtbarwerden verbindet sie sich neu und frischt ihr FCM-Token auf. - Halb offene Verbindungen, bei denen das Gerät einschläft, ohne FIN/RST zu
senden, werden vom Heartbeat nach
CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS(Default 180) ohne Lebenszeichen geschlossen. Als Lebenszeichen zählt ein Code-2-Pong oder jede andere eingehende WebSocket-Nachricht des Clients. - Jeder WSGI-Worker hinterlässt ein Lebenszeichen in
ws_workers. Clients eines nicht mehr laufenden Workers – etwa nach einem Neustart – werden automatisch als getrennt markiert. Das verhindert dauerhaft „verbundene“ Karteileichen in der Datenbank.
Ohne Schritt 3 und 4 blieben schlafende Geräte bzw. Clients aus einem alten
Prozess dauerhaft als „verbunden“ markiert und würden nie als Wake-Kandidaten
erscheinen. ws_clients-Einträge mit gültigem FCM-Token werden beim normalen
Client-Aufräumen nicht entfernt; das Token hat eine eigene, großzügigere
Aufbewahrungsfrist.
Offline-Timeout
Ein periodischer Worker prüft getrennte Clients. Nach
CMBNET_FCM_OFFLINE_WAKE_MINUTES (Default 5 Minuten) wird ein Signal gesendet,
auch wenn keine Nachricht in der Queue liegt. Damit erhält die Gruppen-View
die Gelegenheit, ein Positionsupdate zu senden. Für die Gruppen-View gilt das
nur, wenn auto_position aktiviert ist; Dispatcher-Mobil-Clients werden
ebenfalls berücksichtigt, haben aber keine automatische Positionsübertragung.
Manuell
Der Radar-Button im Desktop-Dispatcher und im mobilen Dispatcher ruft
POST /<tenant>/api/push/wake auf. Der mobile Dispatcher schränkt den Aufruf
auf die aktuell ausgewählte Gruppe ein, sofern eine Gruppe gewählt ist. Der
Desktop-Dispatcher weckt alle mobilen Clients mit gültigem Token – auch
solche, die der Broker noch als verbunden führt. Ein kurzer Cooldown
verhindert versehentliche Doppelklicks.
Client-Typen
Nur diese Werte sind zugelassen:
group_viewfür Accounts der RolleGruppedispatcher_mobilefür Accounts der RolleDispatcheroderAdministrator
Der Typ wird beim Code-0-Handshake vom Client mitgesendet und serverseitig gegen die Session-Rolle geprüft. Ohne gültigen Typ werden keine FCM-Tokens angenommen und keine Wake-Signale versendet. Der Observer-View und der Desktop-Dispatcher erhalten keine FCM-Behandlung.
Datenbank
ws_clients wurde ergänzt um:
client_type: Client-Typ für das FCM-Routinglast_wake_at,last_wake_reason: Drosselung und Nachvollziehbarkeit
Neue Tabelle ws_workers:
- Lebenszeichen je WSGI-Worker (
started_at,heartbeat_at) - dient der Erkennung verwaister Clients nach einem Worker-Neustart
Neue Tabelle ws_push_tokens:
- ein FCM-Token ist projektweit eindeutig
- Zuordnung zu Mandant, Account, Client-ID und Client-Typ
auto_positionfür die periodische Positionsweckunginvalidfür von FCM abgelehnte Tokens
Die Registrierung wird bei einem Reload mit neuer Client-ID auf die neue
Client-ID verschoben. Nach einer Token-Rotation wird das alte Token derselben
Webview entfernt. Verwaiste Tokens werden mit einer eigenen Frist aufgeräumt;
der zugehörige ws_clients-Eintrag bleibt so lange erhalten. Die
Client-Queues werden weiterhin nach der kürzeren Queue-Frist bereinigt.
Mehrere Worker
Jeder WSGI-Worker besitzt einen eigenen Push-Worker. Die Kandidatenauswahl
erfolgt deshalb in einer SQLite-Transaktion (BEGIN IMMEDIATE). Der erste
Worker reserviert die Clients über last_wake_at; alle anderen sehen sie in
diesem Lauf nicht mehr. Der eigentliche FCM-Versand findet nach dem Commit
statt. Das verhindert doppelte Signale bei mehreren Gunicorn-Workern.
Konfiguration
Alle Werte sind optional; ohne CMBNET_FCM_ENABLED=1 bleibt FCM vollständig
inaktiv:
| Variable | Default | Bedeutung |
|---|---|---|
CMBNET_FCM_ENABLED |
0 |
FCM aktivieren |
CMBNET_FCM_SERVICE_ACCOUNT_FILE |
– | Pfad zum Service-Account-JSON |
CMBNET_FCM_SERVICE_ACCOUNT_JSON |
– | Service Account als JSON-String |
CMBNET_FCM_PROJECT_ID |
aus Credentials | Firebase-Projekt |
CMBNET_FCM_WEB_API_KEY |
– | Öffentlicher Web-API-Key |
CMBNET_FCM_WEB_AUTH_DOMAIN |
<projekt>.firebaseapp.com |
Auth-Domain |
CMBNET_FCM_WEB_PROJECT_ID |
CMBNET_FCM_PROJECT_ID |
Web-Projekt-ID |
CMBNET_FCM_WEB_STORAGE_BUCKET |
<projekt>.appspot.com |
Storage-Bucket |
CMBNET_FCM_WEB_MESSAGING_SENDER_ID |
– | Sender-ID |
CMBNET_FCM_WEB_APP_ID |
– | Firebase-Web-App-ID |
CMBNET_FCM_VAPID_KEY |
– | Web-Push-Zertifikat |
CMBNET_FCM_WEB_SDK_VERSION |
10.14.1 |
Firebase-JS-Version |
CMBNET_FCM_OFFLINE_WAKE_MINUTES |
5 |
Offline-Timeout |
CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS |
60 |
Cooldown je Queue-Wake |
CMBNET_FCM_MANUAL_WAKE_COOLDOWN_SECONDS |
15 |
Cooldown für den Button |
CMBNET_FCM_SIGNAL_TTL_SECONDS |
600 |
FCM-TTL |
CMBNET_FCM_WAKE_CONNECTED_CLIENTS |
1 |
Auch als verbunden geltende mobile Clients wecken (iOS) |
CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS |
30 |
Prüfintervall des Workers |
CMBNET_FCM_PUSH_TOKEN_RETENTION_MINUTES |
43200 |
Aufbewahrung nicht verbundener Tokens (30 Tage) |
CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS |
180 |
Zeit ohne Lebenszeichen bis zur Offline-Markierung |
Beschränkungen und Konsequenzen bei PWAs
Allgemein
- Ein Service Worker kann keine dauerhafte WebSocket-Verbindung halten und keine Seite im Hintergrund starten. Das eigentliche Reconnecten und Senden übernimmt immer ein PWA-Fenster.
- Ist die PWA vollständig geschlossen, kann FCM den Service Worker wecken, aber nicht zuverlässig ein Fenster öffnen. Dann bleibt nur eine sichtbare Benachrichtigung; der Nutzer muss sie antippen. Das ist eine Plattform- und keine Implementierungsgrenze.
- Ein Wake-Signal ist eine Aufforderung, keine Garantie. Zustellung kann durch Netz, Energiesparmodus, Firebase oder das Betriebssystem verzögert oder zusammengefasst werden.
- Ein Positionsupdate ist nur möglich, wenn die Seite tatsächlich läuft und der Browser Geolocation im Hintergrund erlaubt. Andernfalls wird die letzte bekannte Position verwendet oder das Update entfällt.
- Die PWA muss über HTTPS ausgeliefert werden. Das Token ist ein installationsbezogenes Geheimnis und sollte nicht geloggt werden.
- FCM ist ein Google-Dienst. Verfügbarkeit, Datenschutz und Netzwerkzugriffe müssen betrieblich bewertet werden.
Android (Chrome/Edge)
- Web Push funktioniert in der installierten PWA und im Browser, sofern Benachrichtigungen erlaubt sind.
- Chrome kann Hintergrundtabs einfrieren. Der Service Worker bleibt für
Push-Events zuständig; die Seite wird beim
postMessagemöglicherweise erst verzögert aktiv. - Hersteller-Energiesparfunktionen und „App beenden“ verhindern Zustellungen.
clients.openWindowist aus einem Push-Event nicht zuverlässig erlaubt; deshalb der Benachrichtigungs-Fallback.
iOS/iPadOS (Safari)
- Web Push ist erst ab iOS/iPadOS 16.4 und nur für zum Home-Bildschirm hinzugefügte PWAs verfügbar. In einem normalen Safari-Tab wird kein FCM-Token registriert.
- Benachrichtigungen müssen ausdrücklich erlaubt werden. Ohne Erlaubnis bleibt die App offline, bis sie manuell geöffnet wird.
- iOS kann Hintergrund-Pushes stark drosseln oder zusammenfassen. Ein stilles Data-Push ist nicht garantiert; der sichtbare Benachrichtigungs- Fallback ist Teil des Designs.
- Hintergrund-Geolocation ist stark eingeschränkt. Das garantierte „mindestens ein Positionsupdate“ gilt deshalb nur, solange die Seite nach dem Wake tatsächlich ausgeführt wird.
- APNs/FCM können die Zustellung verweigern, wenn die PWA vom Nutzer entfernt oder die Benachrichtigungserlaubnis entzogen wurde.
Konsequenz für die Bedienung
Die Funktion ist eine beschleunigte Synchronisierung, kein Ersatz für das Öffnen der App. Disponenten sollten bei zeitkritischen Lagen weiterhin den manuellen Radar-Button nutzen und die mobile Gruppe bei Bedarf zusätzlich telefonisch erreichen.