---
title: "API reference"
slug: "api-reference-flutter-engage"
updated: 2026-04-17T09:17:46Z
published: 2026-04-17T09:17:46Z
canonical: "docs.mapp.com/api-reference-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.

# API reference

This reference provides an overview of the available Flutter Bridge API methods in SDK v0.0.13. Use it to quickly check method names, platforms, return types, and expected behavior.

## Initialization and device state

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `engage(String sdkKey, String googleProjectId, SERVER server, String appID, String tenantID, [NotificationMode? notificationMode])` | Android, iOS | `Future<void>` | Initializes the SDK and registers the device. |
| `isReady()` | Android, iOS | `Future<bool>` | Returns whether the SDK is initialized and ready. |
| `getDeviceInfo()` | Android, iOS | `Future<Map<String, dynamic>?>` | Returns metadata for the current device. |

---

## Alias and user identification

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `getAlias()` | Android, iOS | `Future<String>` | Returns the current alias for the device. |
| `setAlias(String alias)` | Android, iOS | `Future<void>` | Replaces the current AUTO alias with a known identifier. |
| `setAliasWithResend(String alias, bool resendCustomAttributes)` | Android, iOS | `Future<void>` | Sets a known alias and optionally re-sends previously stored custom attributes. |
| `logOut(bool pushEnabled)` | Android, iOS | `Future<void>` | Logs out the current user, restores anonymous device state, and controls push behavior after logout. |

---

## Push notifications

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `setPushEnabled(bool enabled)` | Android, iOS | `Future<bool>` | Enables or disables push notifications for the device. |
| `isPushEnabled()` | Android, iOS | `Future<bool>` | Returns the current push opt-in state. |
| `requestPermissionPostNotifications()` | Android 13+ | `Future<bool>` | Requests the Android 13 POST_NOTIFICATIONS runtime permission. |
| `postponeNotificationRequest(bool postponed)` | iOS | `Future<void>` | Defers or allows the iOS notification permission prompt. |
| `showNotificationsOnForeground(bool enabled)` | Android, iOS | `Future<void>` | Controls whether notifications are shown while the app is in the foreground. |
| `removeBadgeNumber()` | iOS | `Future<void>` | Clears the app icon badge count. |
| `handleRemoteMessage(Map data)` | Android | `Future<void>` | Forwards a Firebase background message to the native Mapp SDK in multi-provider setups. |

---

## Tags

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `addTag(String tag)` | Android, iOS | `Future<bool>` | Adds a tag to the current device or contact context. |
| `getTags()` | Android, iOS | `Future<List<String>>` | Returns all tags for the current device or contact context. |
| `removeTag(String tag)` | Android, iOS | `Future<bool>` | Removes a tag from the current device or contact context. |

---

## Custom attributes

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `setCustomAttributes(Map attributes)` | Android, iOS | `Future<void>` | Sets one or more custom attributes for the current device or contact context. |
| `getCustomAttributes(List? keys)` | Android, iOS | `Future<Map<String, String>>` | Returns custom attributes for the specified keys. |

---

## In-app messaging and inbox

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `triggerInApp(String value)` | Android, iOS | `Future<void>` | Triggers an in-app event by name. |
| `fetchInboxMessage()` | Android, iOS | `Future<dynamic>` | Fetches inbox messages. On Android, messages are returned directly. On iOS, messages are delivered through callbacks. |
| `fetchInBoxMessageWithMessageId(int value)` | Android, iOS | `Future<String?>` | Fetches a specific inbox message by ID. |
| `inAppMarkAsRead(String templateId, String eventId)` | Android, iOS | `Future<void>` | Marks an in-app or inbox message as read. |
| `inAppMarkAsUnread(String templateId, String eventId)` | Android, iOS | `Future<void>` | Marks an in-app or inbox message as unread. |
| `inAppMarkAsDeleted(String templateId, String eventId)` | Android, iOS | `Future<void>` | Marks an in-app or inbox message as deleted. |

---

## Geolocation and geofencing

| Method | Platform | Returns | Description |
| --- | --- | --- | --- |
| `startGeoFencing()` | Android | `Future<String>` | Starts geofence monitoring. |
| `stopGeoFencing()` | Android | `Future<String>` | Stops geofence monitoring. |

---

## Callback properties

| Property | Platform | Payload | Description |
| --- | --- | --- | --- |
| `handledRemoteNotification` | Android, iOS | `dynamic` | Triggered when a push notification is received. |
| `handledPushOpen` | Android, iOS | `dynamic` | Triggered when the user opens a notification. |
| `handledPushDismiss` | Android | `dynamic` | Triggered when a notification is dismissed. |
| `handledPushSilent` | Android | `dynamic` | Triggered for silent or data-only pushes. |
| `handledRichContent` | Android, iOS | `dynamic` | Triggered when rich push media is available. |
| `didReceiveInappMessageWithIdentifier` | Android, iOS | `dynamic` | Triggered when an in-app message is ready to display. |
| `didReceiveInBoxMessage` | iOS | `dynamic` | Triggered when a single inbox message is delivered. |
| `didReceiveInBoxMessages` | iOS | `dynamic` | Triggered when multiple inbox messages are delivered. |
| `inAppCallFailedWithResponse` | Android, iOS | `dynamic` | Triggered when an in-app API call fails. |
| `didReceiveDeepLinkWithIdentifier` | Android, iOS | `dynamic` | Triggered when a deep link is received. |
| `didReceiveCustomLinkWithIdentifier` | Android, iOS | `dynamic` | Triggered when a custom link action is received. |

---

## Enums

### NotificationMode

| Value | Description |
| --- | --- |
| `backgroundAndForeground` | Shows notifications in the background and foreground. |
| `backgroundOnly` | Shows notifications only when the app is in the background. |
| `silentOnly` | Receives push payloads without displaying a visible notification. |

### SERVER

| Value | Description |
| --- | --- |
| `SERVER.L3` | Mapp EU production server. |
| `SERVER.L3_US` | Mapp US production server. |
| `SERVER.EMC` | EMC EU server. |
| `SERVER.EMC_US` | EMC US server. |