---
title: "API Reference"
slug: "api-reference-react-native-engage"
updated: 2026-09-03T14:22:41Z
published: 2026-09-03T14:22:41Z
canonical: "docs.mapp.com/api-reference-react-native-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

## Introduction

Complete list of all public methods in the Mapp Engage React Native Plugin, grouped by function. Platform availability: **Both** = iOS and Android, **iOS** = iOS only, **Android** = Android only. An asterisk (*) indicates the method exists on both platforms but is a no-op on the indicated platform in the current SDK version.

## Initialization & Status

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `engage(sdkKey, googleProjectId, server, appID, tenantID)` | Promise<boolean> | Both | Initializes the SDK. On iOS, only `server` is used. Since 2.0.0, returns a promise — await it before calling APIs that depend on the native Mapp singleton. |
| `engageTestServer(cepUrl, sdkKey, googleProjectId, server, appID, tenantID)` | void | Android | Initializes against a custom CEP test endpoint. |
| `isReady()` | Promise<boolean> | Both | Returns true when the SDK is initialized. |
| `onInitCompletedListener()` | Promise<void> | Android | Resolves when initialization completes. |
| `addInitListener(listener)` | EmitterSubscription | iOS | Fires when iOS SDK initialization completes. |

> [!NOTE]
> Note
> 
> Changed in 2.0.0: `engage()` now returns a promise instead of `void`. Await it before calling APIs that depend on the native Mapp singleton, such as `isReady()` or `isDeviceRegistered()`. See [Breaking Changes in 2.0.0](/docs/en/breaking-changes-2-0-0-react-native-engage).

## Device & Registration

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `isDeviceRegistered()` | Promise<boolean> | Both | Returns true when the device is registered with Mapp. |
| `getDeviceInfo()` | Promise<Object> | Both | Returns general device information. |
| `getDeviceDmcInfo()` | Promise<any> | Android | Returns device DMC configuration from the Mapp backend. Returns null on iOS. |

## Push Notifications

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `isPushEnabled()` | Promise<boolean> | Both | Returns true when push notifications are enabled. |
| `setPushEnabled(optIn)` | void | Both | Enables or disables push notifications. |
| `requestPostNotificationPermission()` | Promise<boolean> | Both | Requests POST_NOTIFICATIONS permission on Android 13+. Returns true on iOS without prompting. |
| `setPostponeNotificationRequest(postpone)` | void | iOS | Delays the system notification permission prompt. Call before `engage()`. |
| `showNotificationAlertView()` | void | iOS | Triggers the iOS notification permission dialog. |
| `setShowNotificationsAtForeground(value)` | void | iOS | Controls notification display when the app is in the foreground. |
| `setToken(token)` | Promise<boolean> | Both | Sets the FCM registration token manually. Since 2.0.0, iOS rejects with `INVALID_APNS_TOKEN` for a value that is not a base64-encoded native APNs token. |
| `getToken()` | Promise<string> | Both | Returns the current FCM registration token. Since 2.0.0, rejects on failure instead of resolving or crashing — see the note below. |
| `setRemoteMessage(remoteMessage)` | void | Both | Forwards a Firebase remote message to the Mapp SDK for processing. |
| `isPushFromMapp(remoteMessage)` | Promise<boolean> | Both | Returns true if the remote message originates from Mapp. |
| `clearNotifications()` | void | Both | Clears all app notifications from the notification tray. |
| `clearNotification(identifier)` | void | Both | Clears a specific notification by identifier. |
| `removeBadgeNumber()` | void | Both* | Removes the app badge number. No-op on Android SDK v7. |
| `addPushListener(listener)` | EmitterSubscription | Both | Subscribes to push notification events. |
| `removePushListener(listener)` | void | Both | Removes a push notification listener. |
| `addDeepLinkingListener(listener)` | EmitterSubscription | Both | Subscribes to deep link events from push notifications. |
| `removeDeepLinkingListener(listener)` | void | Both | Removes a deep link listener. |

> [!WARNING]
> Warning
> 
> Changed in 2.0.0: `getToken()` now rejects instead of crashing (Android) or silently failing (iOS). Android rejects with `FCM_REGISTRATION_FAILED`; iOS rejects with `APNS_TOKEN_UNAVAILABLE`, because Mapp's auto-integration owns the native APNs token. Wrap calls in try/catch. See [Breaking Changes in 2.0.0](/docs/en/breaking-changes-2-0-0-react-native-engage).

## GeoFencing

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `requestGeofenceLocationPermission()` | Promise<boolean> | Both | Requests location permission required for geofencing. Since 2.0.0, Android shows the foreground and, when required, background permission dialogs, instead of only checking the current state. |
| `startGeoFencing()` | Promise<string> | Both | Starts geofence region monitoring. Deprecated since 2.0.0 — use `startGeofencing()`. |
| `stopGeoFencing()` | Promise<string> | Both | Stops geofence region monitoring. Deprecated since 2.0.0 — use `stopGeofencing()`. |
| `startGeofencing()` | Promise<string> | Both | Starts geofence region monitoring. The preferred spelling since 2.0.0. `startGeoFencing()` remains available but is deprecated. |
| `stopGeofencing()` | Promise<string> | Both | Stops geofence region monitoring. The preferred spelling since 2.0.0. `stopGeoFencing()` remains available but is deprecated. |

> [!NOTE]
> Note
> 
> Changed in 2.0.0: `requestGeofenceLocationPermission()` can now display system permission dialogs on Android. Call it from a clear user interaction, and only after explaining why your application needs location access. See [Breaking Changes in 2.0.0](/docs/en/breaking-changes-2-0-0-react-native-engage).

## In-App Messaging

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `triggerInApp(value)` | void | Both | Triggers an in-app message by event name. |
| `fetchInboxMessage()` | Promise<any> | iOS | Fetches inbox messages. Results delivered via `addInboxMessagesListener`. |
| `fetchLatestInboxMessage()` | Promise<any> | Both | Fetches the latest inbox message. |
| `addInboxMessagesListener(listener)` | EmitterSubscription | iOS | Receives the full inbox message list after `fetchInboxMessage()`. |
| `addInboxMessageListener(listener)` | EmitterSubscription | iOS | Receives individual inbox message events. |
| `addRichMessagesListener(listener)` | EmitterSubscription | iOS | Receives rich push message content. |
| `inAppMarkAsRead(templateId, eventId)` | void | Both | Marks an inbox message as read. Since 2.0.0, Android also updates the message status on the Mapp backend — previously a no-op. |
| `inAppMarkAsUnRead(templateId, eventId)` | void | Both | Marks an inbox message as unread. Since 2.0.0, Android also updates the message status on the Mapp backend — previously a no-op. |
| `inAppMarkAsDeleted(templateId, eventId)` | void | Both | Marks an inbox message as deleted. Since 2.0.0, Android also updates the message status on the Mapp backend — previously a no-op. |
| `triggerStatistic(templateId, originalEventId, trackingKey, displayMillis, reason, link)` | string | Android* | Tracks an in-app message statistic. No-op in Android SDK v7. |

> [!NOTE]
> Note
> 
> Changed in 2.0.0: `inAppMarkAsRead`, `inAppMarkAsUnRead`, and `inAppMarkAsDeleted` now call Mapp Engage 7.1.2 to update the message's server-side status on Android, instead of doing nothing. This is intended, but it introduces a network and backend side effect where there was none before. The legacy `eventId` argument remains accepted for source compatibility; the message is identified by `templateId`. See [Breaking Changes in 2.0.0](/docs/en/breaking-changes-2-0-0-react-native-engage).

## User Data

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `setAlias(alias, resendAttributes?)` | Promise<boolean> | Both | Sets the device alias. Pass `true` as second argument to resend stored custom attributes to the backend. |
| `getAlias()` | Promise<string> | Both | Returns the current device alias. |
| `setAttributes(attributes)` | void | Both | Sets multiple custom attributes from an object. |
| `getAttributes(keys)` | Promise<Object> | Both | Returns values for the specified attribute keys. |
| `setAttributeString(key, value)` | void | Both | Sets a single string custom attribute. |
| `setAttributeInt(key, value)` | void | Both | Sets a single integer custom attribute. |
| `getAttributeStringValue(key)` | Promise<string> | Both | Returns the string value of a custom attribute. |
| `removeAttribute(key)` | void | Android | Removes a custom attribute by key. |
| `incrementNumericKey(key, value)` | void | iOS | Increments a numeric custom attribute by the given value. |
| `addTag(tag)` | void | Both | Adds a tag to the device. |
| `removeTag(tag)` | void | Both | Removes a tag from the device. |
| `getTags()` | Promise<string[]> | Both | Returns all tags set on the device. |
| `addCustomEvent(event)` | Promise<void> | Both | Sends a `CustomEvent` object to the Mapp backend. |
| `runAction(name, value?)` | Promise<any> | Android | Executes a named SDK action. Used internally by `addCustomEvent()`. |
| `logOut(pushEnabled)` | void | Both | Clears the user identity. Pass `true` to keep push active after logout. |

## Screen Orientation

| Method | Returns | Platform | Description |
| --- | --- | --- | --- |
| `lockScreenOrientation(value)` | void | Android* | Locks or unlocks screen orientation. No-op in Android SDK v7. |