mcpField
M
maui-local-notifications

maui-local-notifications

github.com/davidortinauDevelopment17651 installsUpdated 16w ago
Repository

About maui-local-notifications

A .NET MAUI implementation guide for developers adding local notifications across platforms. It outlines service design, platform-specific setup and pitfalls, and Windows scheduling limitations.

Key features

  1. 01Cross-platform notification service design
  2. 02Android permission and channel setup
  3. 03Rescheduling notifications after Android reboot
  4. 04Foreground notification handling on iOS and Mac Catalyst
  5. 05Windows scheduled notification limitation

Use cases

  1. 01Implement immediate local notifications
  2. 02Schedule reminders that survive Android reboot
  3. 03Troubleshoot notification permissions or foreground display
  4. 04Plan notification behavior around platform capabilities

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/davidortinau/maui-skills --skill maui-local-notifications

After installing, type/maui-local-notificationsin Claude Code to confirm it loaded.

Bundled filesreferences/local-notifications-api.md

Details

From the project README

.NET MAUI Local Notifications

Implementation overview

  1. Define cross-platform INotificationManagerService interface and event args
  2. Implement Android notification service (channel, AlarmManager, BroadcastReceiver)
  3. Implement iOS/Mac Catalyst notification service (UNUserNotificationCenter)
  4. Register platform implementations via DI
  5. Configure platform permissions and MainActivity

See references/local-notifications-api.md for full implementation code.

Platform gotchas

Android
IssueFix
Notifications silently fail on API 33+Must request POST_NOTIFICATIONS runtime permission first
PendingIntent crash on Android 12+Must include PendingIntentFlags.Immutable for API 31+
Scheduled notifications lost on rebootAlarmManager does not survive device restart — re-schedule on boot via BOOT_COMPLETED receiver
No notification appearsChannel not created — required on API 26+ (Android 8.0)
Notification tap doesn't return to appLaunchMode = LaunchMode.SingleTop must be set on MainActivity
// ✅ Correct — API 31+ requires Immutable flag
var pendingIntentFlags = (Build.VERSION.SdkInt >= BuildVersionCodes.S)
    ? PendingIntentFlags.CancelCurrent | PendingIntentFlags.Immutable
    : PendingIntentFlags.CancelCurrent;

// ❌ Wrong — crashes on Android 12+
var pendingIntentFlags = PendingIntentFlags.CancelCurrent;
iOS / Mac Catalyst
IssueFix
No notification prompt appearsPermission already denied — user must re-enable in Settings
Foreground notifications don't showMust implement UNUserNotificationCenterDelegate and set Current.Delegate
Notification shows Alert not BannerUse UNNotificationPresentationOptions.Banner on iOS 14+
// ✅ iOS 14+ — use Banner
completionHandler(OperatingSystem.IsIOSVersionAtLeast(14)
    ? UNNotificationPresentationOptions.Banner
    : UNNotificationPresentationOptions.Alert);

// ❌ Always using Alert — deprecated on iOS 14+
completionHandler(UNNotificationPresentationOptions.Alert);
Windows

⚠️ Windows App SDK supports toast notifications but scheduled notifications are not yet supported. Immediate notifications work.

DI registration — platform-specific only

// ✅ Must use #if guards — there's no cross-platform implementation
#if ANDROID
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.Android.NotificationManagerService>();
#elif IOS
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.iOS.NotificationManagerService>();
#elif MACCATALYST
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.MacCatalyst.NotificationManagerService>();
#endif

Common anti-patterns

// ❌ Sending without checking permission — silent failure on API 33+
notificationManager.SendNotification("Title", "Body");

// ✅ Request permission first
#if ANDROID
var status = await Permissions.RequestAsync<Platforms.Android.NotificationPermission>();
if (status != PermissionStatus.Granted) return;
#endif

// ❌ Updating UI directly from notification callback — cross-thread exception
notificationManager.NotificationReceived += (s, e) =>
    myLabel.Text = ((NotificationEventArgs)e).Title;

// ✅ Marshal to UI thread
notificationManager.NotificationReceived += (s, e) =>
    MainThread.BeginInvokeOnMainThread(() =>
        myLabel.Text = ((NotificationEventArgs)e).Title);

Decision framework

NeedApproach
Immediate notificationSendNotification(title, message) with null notifyTime
Scheduled reminderSendNotification(title, message, DateTime.Now.AddMinutes(30))
Persist across reboot (Android)Add BOOT_COMPLETED receiver to re-schedule alarms
Rich notifications (images, actions)Extend platform implementations with native APIs
Push notifications from serverUse a different pattern entirely (FCM/APNs)

Quick checklist

  • Cross-platform INotificationManagerService interface defined
  • Android: notification channel created (API 26+)
  • Android: POST_NOTIFICATIONS permission in manifest + runtime request (API 33+)
  • Android: PendingIntentFlags.Immutable used (API 31+)
  • Android: MainActivity has LaunchMode.SingleTop and handles OnNewIntent
  • iOS: UNUserNotificationCenterDelegate set for foreground display
  • iOS: Banner used instead of Alert on iOS 14+
  • DI registration uses #if platform guards
  • UI updates from notification callbacks use MainThread.BeginInvokeOnMainThread

Comments

Markdown supported