notibase_flutter 0.5.1

Official Flutter SDK for Notibase — push registration, identity, events, attribution and the in-app inbox. Pure Dart, no native code: pass us the token from firebase_messaging and everything else is o [...]

notibase_flutter

Push notifications, in-app inbox and click tracking for Flutter — pure Dart, one dependency.
Documentation · pub.dev · Console

---

Official Flutter SDK for Notibase. Pure Dart — no native code and a single dependency (shared_preferences), so it adds nothing to your build complexity and can never conflict with your Firebase setup.

flutter pub add notibase_flutter firebase_messaging url_launcher

New to push? The guide walks Firebase and APNs from empty accounts: notibase.dev/flutter.html

How it fits together

Your app keeps using firebase_messaging for the platform push plumbing (you likely already do). attachFirebase takes the object you already have and wires everything to it:

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:notibase_flutter/notibase_flutter.dart';
import 'package:url_launcher/url_launcher.dart';

await Notibase.configure('ck_live_…');   // client key — public by design

await Notibase.attachFirebase(
  FirebaseMessaging.instance,
  onMessageOpenedApp: FirebaseMessaging.onMessageOpenedApp,
  onUrl: (url) => launchUrl(Uri.parse(url), mode: LaunchMode.externalApplication),
);

// after login — signature minted by YOUR backend (docs → Security)
await Notibase.identify('user-42', signature: sig, attributes: {'plan': 'pro'});

await Notibase.track('level_complete', properties: {'level': 3});

final items = await Notibase.inbox();
await Notibase.inboxMarkRead([items!.first.id]);

That one call requests notification permission, registers the current token, registers it again every time Firebase rotates it, and records notification opens on both paths — a tap that resumed a backgrounded app, and a tap that cold-started it. Every piece is still public if you would rather wire it yourself: registerPushToken, trackNotificationOpen.

onMessageOpenedApp is a static on the FirebaseMessaging class rather than something the instance can reach, so it has to be handed in separately.

firebase_messaging is your dependency, not ours. This package never imports it — attachFirebase calls it structurally, so apps that obtain a token another way pay nothing for the convenience and a Firebase major version cannot break this package's build.

Where a tap goes

onUrl is where a message composed with a URL goes, and it is the one line that stays yours. Flutter cannot open a URL without a plugin, and making url_launcher a dependency of this package would force it on every app — including the many that route notifications through their own navigator and never want a browser. Point it at your router instead:

onUrl: (url) => navigatorKey.currentState?.pushNamed(Uri.parse(url).path),

Leave it out and a notification's URL is quietly dropped, so the SDK logs one line the first time that happens. Notibase.onNotificationUrl sets the same hook outside attachFirebase.

Attribution

Installs, sessions and revenue are reported for you. install goes out once and session_start on each cold start, as soon as the device is registered — which is what lets a campaign link be credited with the installs it drove.

// a deep link that opened the app
await Notibase.handleDeepLink(uri.toString());

await Notibase.trackPurchase(9.99, productId: 'pro_monthly');

Notibase.autoTrackSessions = false turns the automatic events off. Full model: notibase.dev/attribution.html

Setup test

Most of what goes wrong during an integration is invisible from inside the app: credentials that were never uploaded, a client key belonging to another app, a device that never actually registered. One call prints the answer — and it shows up in the console under Settings → Push platforms:

if (kDebugMode) await Notibase.runSetupTest();

Rich payloads

Pure Dart with no platform channels means this package does not draw notifications — firebase_messaging and the OS do. What it gives you is the structured extras, already parsed, for wiring into flutter_local_notifications:

final n = NotibaseNotification.parse(message.data);
if (!n.isNotibase) return;              // someone else's notification
for (final b in n.buttons) { /* b.id, b.text, b.url */ }
n.mediaUrl;      // ios.media / image
n.largeIconUrl;  // Android only

Verification

CI is the gate (.github/workflows/flutter-sdk.yml): flutter analyze, unit tests against an in-process mock server (auth headers, retry policy, 4xx no-retry, parsing), and a full e2e where the exact shipped core runs against the real Notibase API (register idempotency, HMAC identify enforcement, track, send → inbox → markRead) with database-side assertions.

Security model

The ck_ client key ships inside the app and is public by design (Arch §5.3): it can only register devices, identify with an HMAC signature your backend mints, track events, and read its own device's inbox. Server keys (sk_) are refused at configure time with a teaching error.

Support

• Docs: notibase.dev/flutter.html
• Issues & feature requests: [e-mail]
• Security reports: [e-mail]

License

MIT © Notibase — see LICENSE.

_{This repository is a published snapshot of the Notibase SDK, updated automatically on each release.}