Platform setup

Before using Mapp Engage features in Flutter, make sure your Android and iOS projects are configured for the platform capabilities your integration requires. This includes push notification support and, if applicable, location permissions for geofencing.

This page covers the platform-specific setup requirements that should be in place before testing your Flutter integration.

What this setup page covers

The Flutter plugin acts as a bridge to the native Mapp Engage SDKs on Android and iOS. Because of that, some setup steps must be completed in the native platform projects.

Platform setup typically includes:

• Push notification capabilities

• Permission declarations

• Platform-specific messaging setup

• Location permissions if geofencing is used

Complete the sections relevant to the features your app uses.

Android setup

On Android, make sure your project is ready to receive and display push notifications. If your app uses geofencing, also declare the required location permissions.

A typical Android setup includes:

• Firebase Cloud Messaging support where required by your app setup

• Notification permission handling on Android 13 and later

• Location permissions if geofencing is enabled

For standard single-provider push integrations, the Flutter plugin includes built-in handling for Mapp push notifications.

Android notification permission

Android 13 and later require the POST_NOTIFICATIONS runtime permission before notifications can be displayed.

Request this permission in your Flutter app when notifications become relevant to the user journey.

final bool granted = await MappSdk.requestPermissionPostNotifications();

if (!granted) {
  // Explain the value of notifications or update the UI accordingly
}

This step is part of your app flow, but it should be considered during platform setup because notification delivery depends on it.

Android geofencing permissions

If your app uses geofencing, declare the required location permissions in AndroidManifest.xml.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

These permissions are required for background geofence monitoring on Android.

Android multi-provider messaging setup

If your app uses Mapp together with firebase_messaging 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 native Mapp 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. Standard single-provider integrations do not need this forwarding step.

iOS setup

On iOS, your Xcode project must be configured for push notifications before remote notification features can work correctly.

A typical iOS setup includes:

• Push Notifications capability

• Background Modes for remote notifications

• APNs configuration for the app

• Location permissions in Info.plist if geofencing-related features are used elsewhere in the app

Make sure these platform prerequisites are in place before testing push delivery on iOS.

iOS capabilities in Xcode

Enable the native capabilities required for remote notifications in your Xcode project.

At minimum, review the following:

• Push Notifications

• Background Modes with remote notification support enabled

Without these capabilities, push features may not behave as expected on iOS.

iOS APNs configuration

Your iOS app must also be configured for Apple Push Notification service (APNs). This setup is managed in your Apple Developer and Xcode environment.

Make sure your app uses a valid APNs configuration before testing push notifications in iOS builds.

If APNs is not configured correctly, the Flutter integration can initialize successfully while push delivery still fails.

iOS location permissions

If your app uses location-based features, add the required location permission keys to Info.plist and request permission in the app at the appropriate time.

This applies only if your implementation includes location-dependent features.

Coordinate platform setup with app initialization

Platform setup and Flutter initialization work together. Native platform requirements must be in place before the Flutter plugin can use the corresponding features successfully.

A typical integration flow looks like this:

1. Complete native platform setup for Android and iOS

2. Add the Flutter dependency

3. Initialize the SDK with MappSdk.engage(...)

4. Request permissions when needed in the app flow

5. Configure feature-specific behavior such as push, aliases, or inbox handling

Common mistakes

• Testing push notifications before native platform capabilities are configured

• Skipping the Android 13 notification permission flow

• Using the Android multi-provider forwarding setup when the app has only one push provider

• Forgetting required location permissions for geofencing

• Assuming successful SDK initialization means platform push setup is complete

Best practices

• Complete native platform setup before troubleshooting SDK behavior

• Keep Android and iOS requirements documented separately in your project

• Request permissions at a meaningful point in the user journey

• Enable only the capabilities required by the features your app actually uses

• Test push setup and permission handling on both platforms independently