--- title: "Push notifications" slug: "push-notifications-flutter-engage" updated: 2026-04-17T09:17:13Z published: 2026-04-17T09:17:13Z canonical: "docs.mapp.com/push-notifications-flutter-engage" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Push notifications The Mapp Engage Flutter plugin supports push notifications on Android and iOS. You can enable or disable push delivery, request platform permissions, control foreground notification behavior, and handle push-related events through callback handlers. This guide covers the standard push setup, platform-specific options, and the Android multi-provider scenario. ## How push notifications work Push support is part of the Flutter Bridge API and depends on a successful SDK initialization. After the SDK is initialized, the device can receive push-related configuration updates and notification events. Push handling includes: - Enabling or disabling push notifications for the device - Requesting permission where required by the platform - Controlling whether notifications are shown in the foreground - Responding to push delivery and user interaction through callbacks Before using push-related methods, make sure the SDK has been initialized successfully. --- ## Enable or disable push notifications Use `setPushEnabled()` to opt the device in or out of push notifications. ```dart await MappSdk.setPushEnabled(true); await MappSdk.setPushEnabled(false); ``` Use `isPushEnabled()` to check the current push opt-in state. ```dart final bool enabled = await MappSdk.isPushEnabled(); print('Push enabled: $enabled'); ``` This is useful when your app needs to reflect the current push state in the UI or react to user-controlled notification settings. --- ## Request notification permission on Android 13 and later Android 13 introduced the `POST_NOTIFICATIONS` runtime permission. Use `requestPermissionPostNotifications()` to request this permission when your app first needs to show notifications. ```dart final bool granted = await MappSdk.requestPermissionPostNotifications(); if (!granted) {  // Update the UI or explain why notifications are useful } ``` This method is relevant only on Android 13 and later. On earlier Android versions and on iOS, it does not request this permission. --- ## Control the iOS notification permission prompt On iOS, you can postpone the OS notification permission prompt until the moment that best fits your user journey. ```dart await MappSdk.postponeNotificationRequest(true); await MappSdk.postponeNotificationRequest(false); ``` Use `true` to defer the prompt and `false` to allow it to appear at the next opportunity. This can help you request notification permission only after you have provided context to the user. --- ## Control foreground notification display Use `showNotificationsOnForeground()` to control whether notifications are displayed visually while the app is open and running in the foreground. ```dart await MappSdk.showNotificationsOnForeground(true); await MappSdk.showNotificationsOnForeground(false); ``` Set this to `true` if you want users to see notification banners even while actively using the app. Set it to `false` if your app handles foreground events without showing a visual notification. --- ## Clear the badge count on iOS Use `removeBadgeNumber()` to clear the badge count on the iOS app icon. ```dart await MappSdk.removeBadgeNumber(); ``` This method is available on iOS only. --- ## Handle push events with callbacks The SDK delivers push-related events through static callback properties on `MappSdk`. Assign the callbacks before calling `engage()` to avoid missing early events. ```dart MappSdk.handledRemoteNotification = (dynamic arguments) {  print('Push received: $arguments'); }; MappSdk.handledPushOpen = (dynamic arguments) {  print('Push opened: $arguments'); }; MappSdk.handledPushDismiss = (dynamic arguments) {  print('Push dismissed: $arguments'); }; MappSdk.handledPushSilent = (dynamic arguments) {  print('Silent push received: $arguments'); }; MappSdk.handledRichContent = (dynamic arguments) {  print('Rich content available: $arguments'); }; ``` | Callback | Platform | Description | | --- | --- | --- | | `handledRemoteNotification` | Android, iOS | Triggered when a push notification is received. | | `handledPushOpen` | Android, iOS | Triggered when the user opens a notification. | | `handledPushDismiss` | Android | Triggered when a notification is dismissed without being opened. | | `handledPushSilent` | Android | Triggered for silent or data-only push delivery. | | `handledRichContent` | Android, iOS | Triggered when rich push media becomes available. | --- ## Standard Android setup For standard Android integrations, the plugin includes a built-in messaging service for Mapp push notifications. No additional Firebase forwarding is required as long as Mapp is the only push provider in the app. This means the standard setup usually consists of: - Initializing the SDK - Enabling push if required by your app flow - Requesting notification permission on Android 13 and later - Assigning callback handlers for push events If your app uses more than one push provider, continue with the multi-provider setup. --- ## Android multi-provider setup If your app uses `firebase_messaging` together with Mapp and another push provider, you must forward incoming background messages to the Mapp SDK. Token forwarding is handled natively — no Dart-side token call is needed. Token forwarding to Mapp is handled in your native Android `FirebaseMessagingService` subclass. Override `onNewToken()` and delegate to `MappMessageHandler.onNewToken()`. There is no Dart API for token forwarding. Forward background messages to the Mapp native SDK from Dart: ```dart @pragma('vm:entry-point') Future _firebaseBackgroundHandler(RemoteMessage message) async {  await MappSdk.handleRemoteMessage(message.data); } FirebaseMessaging.onBackgroundMessage(_firebaseBackgroundHandler); ``` This setup is required only for Android multi-provider scenarios. Single-provider apps do not need to call `handleRemoteMessage()`. --- ## iOS setup considerations On iOS, make sure your project includes the required push capabilities and APNs configuration in Xcode. Your app must be properly configured to receive remote notifications before push features can work as expected. Depending on your feature set, your iOS setup may also require: - Push Notifications capability - Background Modes for remote notifications - APNs certificates or token-based APNs configuration If your app also uses geofencing, add the required location permissions to `Info.plist`. --- ## Recommended push setup flow 1. Assign push callbacks before SDK initialization 2. Initialize the SDK with `MappSdk.engage(...)` 3. Enable push based on your app requirements 4. Request permission where required by the platform 5. Configure foreground behavior if needed 6. Handle push opens, dismissals, and delivery events in your app logic This flow keeps push setup predictable across Android and iOS while making platform-specific steps explicit. --- ## Common mistakes - Assigning push callbacks after SDK initialization and missing early events - Skipping the Android 13 notification permission request - Using the Android multi-provider setup when the app has only one push provider - Forgetting to configure iOS push capabilities in Xcode - Assuming platform behavior is identical on Android and iOS --- ## Best practices - Initialize the SDK before using push-related methods - Assign push callbacks before calling `engage()` - Request notification permission at a deliberate moment in the user journey - Use foreground notification display intentionally instead of relying on default behavior alone - Use the multi-provider setup only when your Android app actually uses multiple push providers --- ## Related topics - [SDK lifecycle and readiness](/docs/en/sdk-lifecycle-and-readiness-flutter-engage) - [Event callbacks](/docs/en/event-callbacks-flutter-engage) - [Deep linking](/docs/en/deep-linking-flutter-engage)