notification_kit 1.1.5

Flutter package for FCM, local and push notifications, permissions, Android notification channels, and notification tap handling with a single initialization call.

notification_kit

A Flutter package that simplifies Firebase Cloud Messaging (FCM) and local notifications with a single initialization call.

The ultimate solution for Flutter Notifications. Instead of writing boilerplate code across multiple files, notification_kit reduces your entire Firebase and notification setup to one single, framework-agnostic initialization call. It abstracts all complex setups while remaining decoupled from your state management or routing system (such as GoRouter, AutoRoute, or GetX).

---

Key Features

• 🚀 Single Call Initialization: Bootstrap Firebase Cloud Messaging (FCM) and local notifications with a single line of code.
• 📱 Cross-Platform Support: Robust handlers for both iOS Notification and Android Notification setups.
• ⚙️ Android Notification Channels: Full support for custom channels and priority controls.
• 🔒 Notification Permission: Seamless startup or runtime permission request handling.
• 🖼️ Rich Notification: Automatically downloads and displays image attachments (Rich Image Notifications).
• 📂 Notification Groups: Group notifications logically on Android to keep the system tray clean.
• 📥 Notification Tap Handling: Easily handle background and foreground notification taps with dedicated callbacks.
• 🔄 Framework Agnostic: Works perfectly with any architectural pattern or routing library.

---

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  notification_kit: ^1.1.5

Then run:

flutter pub get

---

Getting Started

Initialize the bootstrap service in your main() method:

import 'package:flutter/material.dart';
import 'package:notification_kit/firebase_bootstrap.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // The single-call bootstrap that handles all Firebase and Local Notification setup!
  await FirebaseBootstrap.start(
    firebaseOptions: DefaultFirebaseOptions.currentPlatform, // Generated by FlutterFire CLI
    config: const FirebaseBootstrapConfig(
      appName: "My Awesome App",
      channelId: "default_channel",
      channelName: "General Updates",
      channelDescription: "All application alerts and notifications",
      notificationIcon: "@mipmap/ic_launcher",
      enableLogs: true,
      requestPermissionOnStartup: true,
      showForegroundNotification: true,
      clearNotificationsOnLaunch: true,
    ),
    callbacks: FirebaseBootstrapCallbacks(
      onNotificationTap: (payload) {
        debugPrint("User tapped notification: ${payload.title} - ${payload.body}");
        // Redirect user or navigate using your custom routing solution (e.g. GoRouter, Navigator)
      },
      onForegroundMessage: (message) {
        debugPrint("Foreground push message received: ${message.messageId}");
      },
      onTokenRefresh: (token) {
        debugPrint("FCM token refreshed: $token");
        // Save the token to your backend database
      },
      onPermissionGranted: () {
        debugPrint("Notification Permission Granted");
      },
      onPermissionDenied: () {
        debugPrint("Notification Permission Denied");
      },
    ),
  );

  runApp(const MyApp());
}

---

Detailed Integration Examples

Firebase Notification Flutter Setup

With notification_kit, you do not need to manually configure background handlers or listeners. The package registers a top-level Firebase background message handler automatically, ensuring Background Notification delivery works out of the box.

Flutter FCM Example (Firebase Cloud Messaging)

Send a push notification payload from your server or Firebase Console. The payload structure supports both standard text notifications and rich media content:

{
  "to": "<FCM_TOKEN>",
  "notification": {
    "title": "New Product Available!",
    "body": "Check out our latest arrivals now.",
    "image": "https://example.com/image.jpg"
  },
  "data": {
    "route": "/product_details",
    "productId": "12345"
  }
}

When this message is received:

1. If the app is in the background, a Push Notification is shown containing the title, body, and downloaded rich image attachment.
2. If the app is in the foreground, a heads-up Local Notification is displayed.
3. When clicked, onNotificationTap is fired containing the data map payload.

Flutter Push Notification Example (Routing on Tap)

Use the onNotificationTap callback to navigate to specific screens based on the custom notification data:

callbacks: FirebaseBootstrapCallbacks(
  onNotificationTap: (payload) {
    final route = payload.data['route'];
    final productId = payload.data['productId'];
    
    if (route == '/product_details' && productId != null) {
      // Example using GoRouter:
      context.go('/products/$productId');
    }
  },
)

Local Notification Flutter Setup

For scheduling or triggering immediate local notifications programmatically, notification_kit exposes simple utility methods through the underlying local notification service wrapper:

// Display an immediate local notification
await FirebaseBootstrap.showLocalNotification(
  id: 1,
  title: "Instant Alert",
  body: "This is a locally triggered notification.",
  payload: {"key": "value"},
);

// Schedule a local notification
await FirebaseBootstrap.scheduleNotification(
  id: 2,
  title: "Scheduled Alert",
  body: "This notification was scheduled to appear later.",
  scheduledDate: DateTime.now().add(const Duration(minutes: 10)),
  payload: {"key": "value"},
);

---

Configuration Options

FirebaseBootstrapConfig

Option	Type	Default	Description
appName	String	Required	The name of the consuming app, used as fallback notification title.
channelId	String	Required	Android notification channel ID.
channelName	String	Required	User-visible channel name on Android.
channelDescription	String	"General Notifications"	Android notification channel description.
channelGroupId	String?	null	Optional Android notification channel group ID.
channelGroupName	String?	null	Optional Android notification channel group name.
notificationIcon	String	"@mipmap/ic_launcher"	Launch icon name to show in the status bar/alert.
enableLogs	bool	true	Enable internal console logging.
requestPermissionOnStartup	bool	true	Ask for notification permission during start.
showForegroundNotification	bool	true	Force heads-up local alerts when app is open.
clearNotificationsOnLaunch	bool	true	Automatically clear active notifications on init.
logger	Function(String, String)?	null	Optional custom logger function to pipe internal logs.

FirebaseBootstrapCallbacks

Exposes hooks to handle events without locking the package to any routing or state framework:

FirebaseBootstrapCallbacks(
  onNotificationTap: (NotificationPayload payload) { ... },
  onForegroundMessage: (RemoteMessage message) { ... },
  onBackgroundMessage: (RemoteMessage message) { ... },
  onTokenRefresh: (String token) { ... },
  onPermissionDenied: () { ... },
  onPermissionGranted: () { ... },
)

---

Legacy Setup Migration Guide

If you are migrating from a manual Firebase + notification configuration:

1. Delete Custom Files: Remove your manual NotificationService or firebase setup scripts, including manual listeners on FirebaseMessaging.onMessage, FirebaseMessaging.onMessageOpenedApp, and local notification initializers.
2. Move Options configuration: Keep your firebase_options.dart file untouched.
3. Change main(): Integrate the FirebaseBootstrap.start() call inside your main() method before runApp().
4. Wire Navigation/Routing: In your custom onNotificationTap(payload) callback, read payload.data['route'] or payload.data['screen'] and navigate to the target screen.
5. Handle Token Persistence: Instead of writing token savings inside the service, move your storage logic directly inside onTokenRefresh(token).