Davidortinau Maui Skills Maui Local Notifications

.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

// ✅ 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

// ✅ 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

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.