---
title: "Platform setup"
slug: "platform-setup-flutter-engage"
updated: 2026-04-17T09:13:26Z
published: 2026-04-17T09:13:26Z
canonical: "docs.mapp.com/platform-setup-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.
# 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.
```dart
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`.
```xml
```
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:
```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. 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