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
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.

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
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.

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
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.

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
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.

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.