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.

await MappSdk.setPushEnabled(true);
await MappSdk.setPushEnabled(false);

Use isPushEnabled() to check the current push opt-in state.

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.

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.

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.

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.

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.

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');
};

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:

@pragma('vm:entry-point')
Future<void> _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

• Event callbacks

• Deep linking