pushlio_flutter 0.1.11

Pushlio push notification SDK — device registration, rich notifications, delivered/opened receipts, deep links, feature flags and in-app messages.

pushlio_flutter

Pushlio push notification SDK for Flutter — one-line setup, automatic device registration, rich notifications (image + buttons), delivered/opened receipts, deep links. Unlimited subscribers, pay per push. pushlio.app

Migrating from OneSignal? See MIGRATION.md — the API is mirrored, most apps switch with a find-and-replace.

Install

flutter pub add pushlio_flutter

Your app must have Firebase configured (google-services.json / GoogleService-Info.plist).

Usage

await Pushlio.init(
  appId: 'YOUR-APP-ID',              // Panel → Apps
  apiUrl: 'https://pushlio.app/api/ingest',
  // Optional:
  // onBackgroundMessage: myFcmHandler,   // keep your own FCM handler working
  // androidSmallIcon: 'ic_stat_push',    // dedicated status-bar icon
  // androidChannelId: 'pushlio', androidChannelName: 'Notifications',
  // enableLogs: true,
);
await Pushlio.requestPermission();

// Clicks deliver the deep link + params, even from a cold start
Pushlio.onClick((n) => router.go(n.effectiveDeepLink!));

Optional:

Pushlio.login('user_42');            // your own user id (for segments)
Pushlio.setTag('premium', 'true');   // used in segment rules
Pushlio.trackEvent('level_completed', params: {'level': 5});
Pushlio.setSubscribed(false);        // opt-out

Foreground messages (custom in-app UI)

By default a push arriving while the app is open is shown as a normal notification. To take over (e.g. show your own dialog):

Pushlio.onForegroundMessage((n) {
  showMyDialog(title: n.title, body: n.body, onView: () {
    Pushlio.reportOpened(n);          // counts as "opened" in analytics
    router.go(n.effectiveDeepLink!);
  });
  return false;                        // suppress the system notification
});

On iOS also pass iosForegroundPresentation: false to init (the system draws foreground alerts itself there).

How it works

• Android: data-only FCM → the SDK renders the notification itself (big picture, up to 3 action buttons, collapse keys).
• iOS: alert push shown by the system; a tiny Notification Service Extension reports the "delivered" receipt and attaches the big image (template included in extras/nse/ — no App Group needed).
• delivered/clicked receipts are queued locally and flushed when online; the server is idempotent, so duplicates are harmless.
• Only messages marked ph="1" are handled — your app's own FCM traffic is never touched.

Feature Flags & Remote Config

Pro plan only. On the Free plan syncConfig() is a no-op (never hits the network) and flag readers return their defaultValue.

Flip features without a store release — values resolve per device via segments.

if (Pushlio.featureFlag('new_home')) return NewHomePage();
final text = Pushlio.remoteConfig('welcome_text', defaultValue: 'Hi');
final limit = Pushlio.remoteConfigNumber('daily_limit', defaultValue: 10);

await Pushlio.syncConfig();                       // manual refresh (no-op if fetched <12h ago)
await Pushlio.syncConfig(force: true);             // bypass the 12h cache
Pushlio.onConfigChanged.listen((_) => setState(() {}));

Values are cached persistently: offline apps keep the last known values, so your UI never waits on the network. See docs/feature-flags.md.

Dikkat edilecekler

Hepsi sessiz hatalardır: uygulama çökmez, sadece bir şey çalışmaz.

Kendi yerel bildirimlerin varsa. flutter_local_notifications bir singleton'dır; initialize() çağrımız senin tap handler'ını ezer. Bu yüzden init(onOtherNotificationTap:) ver — yoksa kendi bildirim dokunuşların sessizce çalışmaz olur.

Soğuk açılış AYRI bir yoldur: uygulama tamamen kapalıyken yapılan dokunuş onDidReceiveNotificationResponse'a HİÇ gelmez, yalnız getNotificationAppLaunchDetails() ile alınır (eklentinin kendi kuralı). 0.1.5'ten beri Pushlio soğuk açılış dokunuşunu onOtherNotificationTap'e İLETMEZ; kendi getNotificationAppLaunchDetails() okumanı yapman gerekir ve ekran tek kez açılır. 0.1.4 ve öncesinde bu dokunuş iki yoldan da geliyordu → hedef ekran üst üste iki kez açılıyordu.

login() ne zaman çağrılır. init() ağı beklemez; kayıt arka planda sürer. 0.1.5'ten beri init()'ten hemen sonra login() çağırabilirsin — kimlik yerelde saklanır ve kayıt payload'unda taşınır. 0.1.4 ve öncesinde sessizce kayboluyordu (aynısı setTag/trackEvent için de).

Firebase yoksa Pushlio sessizce devre dışı kalır, uygulamanı çökertmez. Cihaz panelde görünmüyorsa önce google-services.json / GoogleService-Info.plist yerinde mi bak. Teşhis için Pushlio.onError(...).

Android ikonu beyaz silüet olmalı — renkli PNG durum çubuğunda beyaz kare görünür. androidAccentColor yalnız bildirim gölgesindeki ikonu renklendirir. Kanal bir kez oluşturulur: androidChannelImportance sonradan değişmez, yeni androidChannelId gerekir.

Publishing

See the repo root guide (maintainers): docs/sdk-yayinlama.md.