---
title: "Breaking Changes in 2.0.0"
slug: "breaking-changes-2-0-0-react-native-engage"
updated: 2026-09-03T14:22:51Z
published: 2026-09-03T14:22:51Z
canonical: "docs.mapp.com/breaking-changes-2-0-0-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.

# 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]
> 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:

```java
@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]
> 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]
> 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:

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

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

> [!NOTE]
> 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:

```javascript
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:

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

Use the documented public method instead:

```javascript
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]
> 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.