Zum Inhalt

Push-Notifications

Mobile-Push läuft über Firebase Cloud Messaging (FCM). Zwei Modi möglich.

Modi

Modus Wer betreibt FCM Welche APK
Shared Vesana-Vendor Standard-APK von /downloads
Eigenes Firebase du selbst Custom-APK mit eigenem google-services.json

Shared-Modus (Standard)

Funktioniert out-of-the-box:

  1. Standard-APK installieren (von /downloads der Instanz)
  2. Login
  3. Push wird automatisch registriert

Voraussetzung: Server-Side Firebase-Service-Account-Key. Bei kommerziellen Lizenzen wird der Key vom Vendor bereitgestellt und liegt unter /opt/vesana/firebase-service-account.json mit FIREBASE_SERVICE_ACCOUNT_PATH Env-Variable.

Bei Tester-/Community-Mode kommt der Key entweder mit dem Setup oder du betreibst ein eigenes Firebase-Projekt.

Eigenes Firebase-Projekt

Wenn du volle Kontrolle über Push haben willst (Compliance, Air-Gapped, eigene Branding-APK):

1. Firebase-Projekt erstellen

console.firebase.google.com → Neues Projekt.

2. Android-App hinzufügen

  • Package: org.vesana.app (oder eigene)
  • google-services.json herunterladen

3. Service-Account-Key generieren

Firebase Console → Projekteinstellungen → Dienstkonten → Neuen privaten Schlüssel generieren → JSON.

4. Key in Vesana hochladen

/admin/push-notifications → Firebase-Key hochladen → JSON-Datei wählen.

Backend speichert den Key, initialisiert Firebase neu, startet die Push-Pipeline.

5. Test-Push senden

Auf der gleichen Seite Test-Push — schickt eine Notification an alle eigenen Geräte.

6. Custom-APK bauen

Da die Standard-APK auf das Shared-Firebase-Projekt zeigt, muss für ein eigenes Projekt eine eigene APK gebaut werden:

cd mobile
./build-custom.sh /path/to/google-services.json
# APK liegt in mobile/android/app/build/outputs/apk/release/app-arm64-v8a-release.apk

Diese APK an die Nutzer verteilen (eigene Download-Seite, MDM, etc.).

Ohne Push

Wenn keinerlei Firebase-Konfiguration vorhanden ist, sind Push-Notifications still inaktiv. Die App läuft normal, Mobile-Push-Channels werden aber überschlagen.

Seit v0.17.x

Firebase-Init-Spam ohne Config gefixt — vorher kam pro Alert ein WARN-Log; jetzt einmaliger INFO-Log + Sticky-Disabled-Flag.

Channels konfigurieren

/notification-channels → Neuer Channel → Typ: Mobile Push:

Feld Bedeutung
Name beliebig
Severity-Filter nur CRIT, WARN+, NO_DATA dazu
Recovery-Notifications auch wenn der Service wieder OK
User-Targeting alle Tenant-User oder ausgewählte
Throttle (s) min. Sekunden zwischen zwei Notifications pro User

User-Targeting (multi-select Dropdown) zeigt nur User, die ein Mobile-Gerät registriert haben.

Geräteverwaltung

/admin/push-notifications:

  • Liste aller registrierten Geräte mit User, Plattform, Device-Name, Letzte-Aktivität
  • Pro Gerät: Entfernen — entzieht das Token, das Gerät bekommt keine Push mehr (App muss sich neu registrieren bei nächstem Login)

Notification-Icon

Die App nutzt ein monochromes weißes Silhouette-Icon für die Notification-Bar. Liegt in android/app/src/main/res/drawable-*/notification_icon.png für jede Display-Density (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi).

Wenn du eine eigene Marken-Variante baust: alle 5 PNGs ersetzen, neu bauen.

Privacy / Datenfluss

flowchart LR
    O[Vesana-API] -->|FCM message| FCM[Firebase Cloud Messaging]
    FCM -->|push| GA[Google Android Push]
    GA --> A[App auf Mobile]

Der Notification-Payload enthält:

  • Titel, Body
  • host_id für Deep-Link
  • Severity

Keine sensitiven Inhalte (kein Wert, kein Hostname-Klartext im Body). Format nach Best Practice für Notification-Privacy.

Limitierungen

  • iOS aktuell nicht unterstützt
  • Bei strikten Corporate-Firewalls muss FCM (fcm.googleapis.com) ausgehend erlaubt sein
  • Air-Gapped: Shared-FCM und Cloud-Firebase nicht möglich. Workaround: lokale FCM-Alternative (z. B. UnifiedPush) — aktuell nicht eingebaut

Anschluss