NotificationAPI Flutter SDK

A Flutter plugin for integrating NotificationAPI push notifications into your mobile app.

🚀 Push Notification Support

Cross-platform push notifications with native performance:

Android: Full FCM (Firebase Cloud Messaging) support
iOS: Direct APN (Apple Push Notifications) integration - no Firebase routing required!

This means you get native iOS push notifications with reduced latency and fewer dependencies.

🚀 Quick Start

1. Installation

Add to your pubspec.yaml:

dependencies:
  notificationapi_flutter_sdk: ^1.0.3

2. Setup (One Line!)

import 'package:notificationapi_flutter_sdk/notificationapi_flutter_sdk.dart';

// That's it! This handles initialization, user identification, and permission requests
await NotificationAPI.setup(
  clientId: 'your_client_id_here',
  userId: 'user123',
  autoRequestPermission: true, // automatically request push permissions
  showForegroundNotifications: true, // show native notifications when app is open
);

3. Listen to Notifications (Optional)

// Listen to notifications received while app is open
// Note: These are automatically shown as native notifications by default
NotificationAPI.onMessage.listen((notification) {
  print('Received: ${notification.title}');
  // Optional: Handle notification data or custom actions
});

// Listen to notifications that opened the app
NotificationAPI.onMessageOpenedApp.listen((notification) {
  print('App opened from: ${notification.title}');
  // Handle deep linking or navigation
});

4. Check Status

// Check if everything is ready
if (NotificationAPI.isReady) {
  print('NotificationAPI is ready to receive notifications!');
}

// Get the push token (FCM on Android, APN on iOS)
String? token = await NotificationAPI.getToken();

📱 Complete Example

import 'package:flutter/material.dart';
import 'package:notificationapi_flutter_sdk/notificationapi_flutter_sdk.dart';

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _setupNotifications();
  }

  Future<void> _setupNotifications() async {
    try {
      await NotificationAPI.setup(
        clientId: 'your_client_id',
        userId: 'user123',
        showForegroundNotifications: true, // Auto-show native notifications
      );

      // Optional: Listen for custom handling
      NotificationAPI.onMessage.listen((notification) {
        print('Foreground notification: ${notification.title}');
        // Notification is automatically displayed as native notification
      });

      NotificationAPI.onMessageOpenedApp.listen((notification) {
        print('App opened from notification: ${notification.title}');
        // Handle navigation or deep linking
        if (notification.deepLink != null) {
          // Navigate to specific screen
        }
      });
    } catch (e) {
      print('Error setting up notifications: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('NotificationAPI Example')),
        body: Center(
          child: Column(
            children: [
              Text('Ready: ${NotificationAPI.isReady}'),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: () async {
                  bool granted = await NotificationAPI.requestPermission();
                  ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Permission: ${granted ? "Granted" : "Denied"}')),
                  );
                },
                child: Text('Request Permission'),
              ),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: () {
                  // Toggle foreground notification display
                  NotificationAPI.setShowForegroundNotifications(false);
                  ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Foreground notifications disabled')),
                  );
                },
                child: Text('Disable Foreground Notifications'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

🌙 Background Notifications (App Closed)

Background notifications are automatically handled by the push package. The SDK uses:

FCM for Android background notifications
APN for iOS background notifications

No additional setup is required for basic background notification handling.

Handling Notification Taps

When users tap a notification while the app is terminated, it's automatically handled:

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _setupNotifications();
  }

  Future<void> _setupNotifications() async {
    await NotificationAPI.setup(
      clientId: 'your_client_id',
      userId: 'user123',
    );

    // Handle notifications that opened the app
    NotificationAPI.onMessageOpenedApp.listen((notification) {
      _handleNotificationTap(notification);
    });
  }

  void _handleNotificationTap(PushNotification notification) {
    print('Notification tapped: ${notification.title}');

    // Handle deep linking or navigation
    if (notification.deepLink != null) {
      // Navigate to specific screen
      Navigator.pushNamed(context, notification.deepLink!);
    }
  }
}

Platform-Specific Setup

Android

Requires Firebase setup for FCM
Background notifications work automatically

iOS

Uses native APN - no Firebase required!
Requires Apple Developer Program membership
Enable Push Notifications capability in Xcode
Background notifications work automatically

🔔 Native Notification Display

Automatic Foreground Notifications

By default, when showForegroundNotifications: true is set in setup(), the SDK automatically displays received notifications as native push notifications even when your app is in the foreground. This provides a consistent user experience.

Notification Behavior

App State	Notification Display
Foreground	Native notification banner/alert (automatic)
Background	System notification (handled by OS)
Terminated	System notification (handled by OS)

Customization Options

await NotificationAPI.setup(
  // ... other parameters
  showForegroundNotifications: true,  // Enable native notifications in foreground
);

// You can also toggle this later
NotificationAPI.setShowForegroundNotifications(false); // Disable
NotificationAPI.setShowForegroundNotifications(true);  // Re-enable

🔧 API Reference