Breaking Changes in 2.0.0

Version 2.0.0 is source-compatible with 1.4.2 for the majority of applications. No documented JavaScript method was removed or renamed, and existing method parameters remain unchanged.

The major version number reflects platform and behavioral changes, not an API break. The most significant is the increased minimum iOS deployment target. Read this page to work out which changes affect your application, then follow the 1.4.2 to 2.0.0 migration guide for the required steps.

Minimum iOS deployment target

The minimum supported iOS deployment target is now 15.1, up from 10.0.

Warning
Applications targeting an iOS version below 15.1 cannot install or build the pod until the deployment target is raised. This is a breaking change even for applications that need no JavaScript changes.

Android dependency resolution

The plugin now exports strict compatibility constraints for the Mapp Engage Android SDK 7.1.2 and Expo SDK 57 runtime:

Kotlin 2.1.20
Coroutines 1.11.0
AndroidX Core 1.18.0
WorkManager 2.10.5
Lifecycle 2.10.0
Play Services Location 21.3.0

Gradle may fail dependency resolution if your application explicitly pins an incompatible version. Applications that already resolve compatible versions need no change.

Custom Android Firebase handling

The plugin no longer registers the Mapp SDK Firebase service by default. com.reactlibrary.MessageService is now the default Mapp push owner.

Applications using the default plugin service need no change. Applications that own a custom FirebaseMessagingService must select custom push ownership and forward callbacks through the native helper:

@Override
public void onMessageReceived(RemoteMessage message) {
    if (!MappPushHelper.handleMessage(getApplication(), message)) {
        // Handle non-Mapp messages.
    }
}

@Override
public void onNewToken(String token) {
    MappPushHelper.handleNewToken(getApplication(), token);
}

For Expo, set android.pushHandling to "custom". A successful manifest merge alone does not forward messages to Mapp.

Note
The full method list for MappPushHelper is covered in the MappPushHelper reference.

Geofence permission behavior

In 1.4.2, Mapp.requestGeofenceLocationPermission() only checked the current Android permission state. In 2.0.0, it requests foreground location and, when required, background location, which can display system dialogs.

Note
Call this method from a clear user interaction, and only after explaining why your application needs location access.

Firebase token failure handling

On Android, Mapp.getToken() now rejects with FCM_REGISTRATION_FAILED when Firebase token registration fails, instead of crashing while reading the failed task result:

try {
  const token = await Mapp.getToken();
} catch (error) {
  // Handle unavailable FCM registration.
}

On iOS, Mapp.getToken() now rejects with APNS_TOKEN_UNAVAILABLE, because Mapp's auto-integration owns the native APNs token.

Mapp.engage() is now awaitable

Mapp.engage(...) now returns a promise. In 1.4.2 it returned immediately, so a call to a singleton-dependent method right after could run before native engagement had finished.

await Mapp.engage(sdkKey, googleProjectId, server, appId, tenantId);

Note
Always await Mapp.engage(...) before calling APIs that use the native Mapp singleton, such as isReady() or isDeviceRegistered(). Existing code that does not await it still runs, so this does not block an upgrade by itself — but add the await where you can.

Inbox status methods now update Mapp

These Android methods were no-ops in 1.4.2:

Mapp.inAppMarkAsRead(templateId, eventId);
Mapp.inAppMarkAsUnRead(templateId, eventId);
Mapp.inAppMarkAsDeleted(templateId, eventId);

In 2.0.0, they call Mapp Engage 7.1.2 to fetch the inbox message and update its server-side status to READ, UNREAD, or DELETED. This is the intended behavior, but it introduces an observable network and backend side effect where there was none before.

The legacy eventId argument is still accepted for source compatibility. Mapp Engage 7.1.2 identifies the message using templateId.

Undocumented iOS native methods

Applications calling these undocumented bridge methods directly will break, because they are no longer exported separately:

NativeModules.RNMappPluginModule.autoengage(...);
NativeModules.RNMappPluginModule.engageInapp(...);

Use the documented public method instead:

await Mapp.engage(sdkKey, googleProjectId, server, appId, tenantId);

On iOS, Mapp.engage(...) still initializes both push and in-app messaging. AppoxeeConfig.plist remains the credential source of truth.

Changes that are not immediate breaks

Mapp.engage2() remains available but is deprecated in favor of Mapp.engage(...).
Mapp.startGeoFencing() remains available but is deprecated in favor of Mapp.startGeofencing().
Mapp.stopGeoFencing() remains available but is deprecated in favor of Mapp.stopGeofencing().
Mapp.setRemoteMessage(), Mapp.isPushFromMapp(), and Mapp.setToken() remain supported while JavaScript is guaranteed to be running. Use MappPushHelper instead for native background or terminated Firebase callbacks.
Android minimum SDK remains 24.
React Native peer requirement remains >=0.84.
Node.js requirement remains >=20.19.4.

Who can upgrade without source changes

Your application may need no source changes if all of the following are true:

Its iOS deployment target is already 15.1 or newer.
Its Android dependencies do not conflict with the exported constraints above.
It uses the plugin's default Android Mapp push service instead of a custom FirebaseMessagingService.
It already handles promise rejection from Mapp.getToken().
It expects the inbox status methods to update the real Mapp message status.
It does not call undocumented native bridge methods directly.

Note
Even then, test push delivery, permission prompts, and inbox status changes on physical devices before releasing the upgrade.

For concrete upgrade steps and replacement examples, continue with the 1.4.2 to 2.0.0 migration guide.

Documentation Index