Skip to content

Push notifications

Mobile push runs over Firebase Cloud Messaging (FCM). Two modes possible.

Modes

Mode Who runs FCM Which APK
Shared Vesana vendor Default APK from /downloads
Own Firebase you Custom APK with own google-services.json

Shared mode (default)

Works out of the box:

  1. Install default APK (from /downloads)
  2. Login
  3. Push registers automatically

Prerequisite: server-side Firebase service account key. For commercial licenses the key is provided by the vendor and lives at /opt/vesana/firebase-service-account.json with FIREBASE_SERVICE_ACCOUNT_PATH env variable.

For tester / Community mode, the key is either delivered with setup or you run your own Firebase project.

Own Firebase project

For full control over push (compliance, air-gapped, own branded APK):

1. Create Firebase project

console.firebase.google.com → New project.

2. Add Android app

  • Package: org.vesana.app (or your own)
  • Download google-services.json

3. Generate service account key

Firebase Console → Project settings → Service accounts → Generate new private key → JSON.

4. Upload key into Vesana

/admin/push-notifications → Upload Firebase key → choose JSON.

Backend stores the key, re-initializes Firebase, starts the push pipeline.

5. Send test push

On the same page Test push — sends a notification to all your devices.

6. Build custom APK

Since the default APK points to the shared Firebase project, your own project needs its own APK:

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

Distribute this APK (your own download page, MDM, etc.).

Without push

If no Firebase config exists at all, push notifications are silently inactive. The app runs normally, mobile-push channels are skipped.

Since v0.17.x

Firebase init spam without config fixed — used to log a WARN per alert; now a one-time INFO + sticky-disabled flag.

Configure channel

/notification-channels → New channel → type Mobile push:

Field Meaning
Name free
Severity filter only CRIT, WARN+, also NO_DATA
Recovery notifications also when the service is back to OK
User targeting all tenant users or selected
Throttle (s) min seconds between two notifications per user

User-targeting (multi-select dropdown) only shows users with a registered mobile device.

Manage devices

/admin/push-notifications:

  • List of all registered devices with user, platform, device name, last activity
  • Per device: Remove — revokes the token, the device gets no more pushes (re-register on next login)

Notification icon

The app uses a monochrome white silhouette icon for the notification bar. Lives at android/app/src/main/res/drawable-*/notification_icon.png for each density (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi).

When building a branded variant: replace all 5 PNGs, rebuild.

Privacy / data flow

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

The notification payload contains:

  • Title, body
  • host_id for deep link
  • Severity

No sensitive content (no value, no plaintext hostname in body). Format follows notification-privacy best practice.

Limitations

  • iOS not supported yet
  • Strict corporate firewalls must allow FCM (fcm.googleapis.com) outbound
  • Air-gapped: shared FCM and cloud Firebase don't work. Workaround: local FCM alternative (e.g. UnifiedPush) — not built in yet

Next