gotify_flutter #

Gotify push notifications for Flutter on Android — self-hosted WebSocket delivery, REST send API, and local notification alerts. No Firebase, no extra PHP backend — connect straight to your Gotify server.

Compatible with Gotify 3.x (tokens returned once on create).

Supported platform: Android only.

Features #

• Login, restore session, and logout
• Real-time Gotify message stream with auto-reconnect
• Send push messages and load message history
• Create Gotify applications and clients via REST
• Local Android notifications for incoming messages
• Optional background keep-alive via Android foreground service
• Yellow [gotify_flutter] debug logs while listening

Installation #

Add the package to your pubspec.yaml:

dependencies:
  gotify_flutter: ^1.0.0

flutter pub get

Android setup #

1. Request INTERNET and POST_NOTIFICATIONS in AndroidManifest.xml.

2. Enable core library desugaring (required by local notifications):

compileOptions {
    isCoreLibraryDesugaringEnabled = true
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

3. Prefer HTTPS for your Gotify server. Cleartext HTTP is only for local development:

<application android:usesCleartextTraffic="true" ...>

4. For closed-app delivery, add foreground-service permissions and service (see Background delivery).

Quick start #

import 'package:gotify_flutter/gotify_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  GotifyBackgroundService.initCommunicationPort();
  runApp(const MyApp());
}

final gotify = GotifyPushClient();

await gotify.login(
  baseUrl: 'https://gotify.example.com',
  username: 'admin',
  password: 'your-password',
  clientName: 'My Flutter App',
);

await gotify.ensureSendApplication();
await gotify.startListening(keepAliveInBackground: true);

gotify.onMessage.listen((msg) {
  // Update your UI
});

await gotify.sendMessage(
  title: 'Hello',
  message: 'Push from Flutter',
  priority: 5,
);

Restore a saved session:

final session = await gotify.restoreSession();
if (session != null) {
  await gotify.startListening(keepAliveInBackground: true);
}

Example #

The package includes an Android example app with a login form:

cd example
flutter pub get
flutter run

Enter your Gotify base URL, username, and password on first launch.

API overview #

GotifyPushClient #

Streams #

• onMessage → GotifyMessage
• onConnectionState → GotifyStreamState (disconnected, connecting, connected, reconnecting)

Logging #

While the listener is active:

[gotify_flutter] Listener starting → https://…
[gotify_flutter] Connection state: connected
[gotify_flutter] Listener active — waiting for push notifications
[gotify_flutter] Message #12 «Title»: body text

How it works #

┌─────────────┐   REST POST /message    ┌──────────────┐
│  Your app / │ ───────────────────────►│ Gotify       │
│  HTTP client│      (app token)        │ Server       │
└─────────────┘                         └──────┬───────┘
                                               │ WebSocket /stream
                                               │ (client token)
                                        ┌──────▼───────┐
                                        │ Flutter app  │
                                        │ (Android)    │
                                        └──────────────┘

• Application token — send only (owned by one Gotify user)
• Client token — receive messages (all clients of that user get pushes)
• Per-client targeting by name is not supported by Gotify; use separate users for per-person delivery

Send a test message (HTTP) #

POST https://gotify.example.com/message
X-Gotify-Key: YOUR_APP_TOKEN
Content-Type: application/json

{
  "title": "Test",
  "message": "Hello from HTTP",
  "priority": 5
}

Background / closed-app delivery (Android) #

Gotify uses a live WebSocket. If the user force-stops the app, the OS kills the process and pushes cannot be received.

To keep receiving after the app is swiped away, Android requires a foreground service with an ongoing notification. With keepAliveInBackground: true this package:

• Starts the service while the app is open (required on Android 12+)
• Shows a low-importance ongoing notification titled Gotify (platform requirement)
• Does not prompt for battery-optimization exemption

GotifyBackgroundService.initCommunicationPort();
await gotify.startListening(keepAliveInBackground: true);

Manifest entries (see the example app):

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_REMOTE_MESSAGING" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<service
    android:name="com.pravera.flutter_foreground_task.service.ForegroundService"
    android:foregroundServiceType="remoteMessaging|dataSync"
    android:exported="false"
    android:stopWithTask="false" />

Add a white status-bar icon at @drawable/ic_stat_gotify (included in the example).

License #

MIT — see LICENSE.

Built by Mirshad KVR · Instagram · LinkedIn · GitHub