Local Notifications Plugin (Objective-C Implementation)

A Flutter plugin for iOS local notifications implemented in Objective-C using the native UserNotifications framework.

Features

• ✅ Request notification permissions
• ✅ Schedule one-time notifications with custom delay
• ✅ Schedule repeating notifications
• ✅ Cancel individual notifications by ID
• ✅ Cancel all notifications
• ✅ Get list of pending notifications
• ✅ Custom notification sounds
• ✅ Foreground notification display
• ✅ Notification tap handling

Platform Support

Platform	Support
iOS	✅ iOS 12.0+
Android	❌ Not implemented

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  kk_local_notifications_objc_plugin:
    path: ../kk_local_notifications_objc_plugin

Usage

Basic Example

import 'package:kk_local_notifications_objc_plugin/kk_local_notifications_objc_plugin.dart';

final plugin = KKLocalNotificationsObjcPlugin();

// Request permissions first
bool granted = await plugin.requestNotificationPermissions();

if (granted) {
  // Schedule a simple notification
  await plugin.scheduleNotification(
    title: 'Hello!',
    body: 'This is a test notification',
    delaySeconds: 5,
  );
}

Advanced Usage

// Schedule notification with custom ID and sound
await plugin.scheduleNotification(
  id: 'my-custom-id',
  title: 'Important Reminder',
  body: 'Don\'t forget your meeting at 3 PM',
  delaySeconds: 10,
  sound: 'default',
);

// Schedule repeating notification (minimum 60 seconds interval)
await plugin.scheduleRepeatingNotification(
  id: 'daily-reminder',
  title: 'Daily Reminder',
  body: 'Time for your daily task!',
  intervalSeconds: 3600, // 1 hour
);

// Cancel specific notification
await plugin.cancelNotification('my-custom-id');

// Get all pending notifications
List<Map<String, dynamic>> pending = await plugin.getPendingNotifications();
print('Pending notifications: ${pending.length}');

// Cancel all notifications
await plugin.cancelAllNotifications();

API Reference

Methods

requestNotificationPermissions()

Request notification permissions from the user.

Future<bool> requestNotificationPermissions()

Returns: true if permissions granted, false otherwise.

scheduleNotification()

Schedule a one-time notification.

Future<Map<String, dynamic>> scheduleNotification({
  String? id,
  required String title,
  required String body,
  int delaySeconds = 5,
  String? sound,
})

Parameters:

• id: Optional custom ID. If not provided, a UUID will be generated
• title: Notification title
• body: Notification body text
• delaySeconds: Delay before showing notification (default: 5)
• sound: Sound name or 'default' (default: 'default')

Returns: Map with success boolean and notification id.

scheduleRepeatingNotification()

Schedule a repeating notification.

Future<Map<String, dynamic>> scheduleRepeatingNotification({
  String? id,
  required String title,
  required String body,
  int intervalSeconds = 60,
  String? sound,
})

Parameters:

• id: Optional custom ID. If not provided, a UUID will be generated
• title: Notification title
• body: Notification body text
• intervalSeconds: Repeat interval in seconds (minimum: 60)
• sound: Sound name or 'default' (default: 'default')

Returns: Map with success boolean and notification id.

cancelNotification()

Cancel a specific notification by ID.

Future<Map<String, dynamic>> cancelNotification(String id)

Parameters:

• id: The notification ID to cancel

Returns: Map with success boolean and cancelledId.

cancelAllNotifications()

Cancel all scheduled and delivered notifications.

Future<Map<String, dynamic>> cancelAllNotifications()

Returns: Map with success boolean and confirmation message.

getPendingNotifications()

Get all pending (scheduled but not yet delivered) notifications.

Future<List<Map<String, dynamic>>> getPendingNotifications()

Returns: List of notification objects with id, title, body, timeInterval, and repeats properties.

Implementation Details

iOS Native Code Structure

The plugin uses the iOS UserNotifications framework with these key components:

1. Permission Handling: Requests alert, sound, and badge permissions
2. Notification Scheduling: Uses UNTimeIntervalNotificationTrigger for timing
3. Delegate Implementation: Handles foreground display and tap events
4. Content Management: Configures notification appearance and behavior

Key Features

• Foreground Display: Notifications appear even when app is active
• Sound Support: Default system sound or custom sounds
• Badge Management: Automatic badge increment
• Error Handling: Comprehensive error reporting via Flutter method channels
• Thread Safety: All callbacks properly dispatched to main queue

Example App

The included example app demonstrates all functionality:

1. Permission Request: Interactive permission handling
2. Notification Scheduling: Forms for creating notifications
3. Real-time Management: View and cancel pending notifications
4. Status Updates: Live feedback on all operations

To run the example:

cd example
flutter run

Requirements

• iOS 12.0 or later
• Xcode 12.0 or later
• Flutter 2.0 or later

Error Handling

Common error codes:

• PERMISSION_ERROR: Permission request failed
• SCHEDULE_ERROR: Notification scheduling failed
• INVALID_INTERVAL: Repeating notification interval too short (< 60s)
• MISSING_ID: Required notification ID not provided

Best Practices

1. Always request permissions first before scheduling notifications
2. Use meaningful IDs for notifications you might need to cancel later
3. Respect minimum intervals for repeating notifications (60 seconds)
4. Test on physical devices - notifications don't work in simulators
5. Handle permission denials gracefully in your app
6. Clean up notifications when no longer needed

Testing

Run the included tests:

flutter test

The test suite covers all public API methods with mock implementations.

Contributing

This plugin serves as an educational example of native iOS plugin development. Feel free to extend it with additional features like:

• Custom notification sounds
• Rich notifications with images
• Action buttons
• Location-based triggers
• Calendar-based scheduling