react-native-mapp-plugin 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,4 +1,19 @@
-## Version 2.0.0 (unreleased)
+## Version 2.0.1 (2026/09/04)
+
+***Bug Fixes***
+
+- iOS: `Mapp.onInitCompletedListener()` now returns a `Promise<boolean>` instead of `null`.
+- iOS: When the SDK is already initialized, `Mapp.onInitCompletedListener()` resolves immediately with `true`.
+- iOS: When the SDK is still initializing, `Mapp.onInitCompletedListener()` waits for the existing `com.mapp.init` native event and removes its one-time listener after resolving.
+- Android: Preserved the existing native `AppoxeeObserver` implementation and behavior of `Mapp.onInitCompletedListener()`.
+- Android/iOS: Preserved the public `Mapp.onInitCompletedListener(): Promise<boolean>` API while providing consistent initialization-waiting behavior on both platforms.
+
+***Tests***
+
+- Added bridge coverage for both iOS readiness paths: already initialized and waiting for the native initialization event.
+- Updated platform-dispatch coverage to verify that Android continues to use the native listener and iOS uses its existing initialization event.
+
+## Version 2.0.0 (2026/09/03)
 
 ***Breaking Changes***
 
@@ -10,6 +25,7 @@
 
 ***Bug Fixes***
 
+- `Mapp.engage(...)` is now awaitable so singleton-dependent calls can safely run after native initialization; engagement failures reject instead of being logged silently.
 - Android: Failed Firebase token registration now rejects with `FCM_REGISTRATION_FAILED` instead of crashing while reading a failed task result.
 - Android: All Mapp engage calls run on the main looper. Background Firebase callbacks wait for a bounded engage attempt and safely return failure after SDK errors, timeout, or interruption.
 - Android/Expo: Mapp and custom push ownership now remove the SDK v7 Firebase service and remain idempotent when prebuild runs repeatedly or changes mode.

package/MIGRATION_2.0.md

@@ -31,7 +31,7 @@ Read [Breaking changes in 2.0.0](BREAKING_CHANGES.md) first to determine which c
 | `Mapp.inAppMarkAsRead(templateId, eventId)` | Android no-op. | Android fetches the Mapp Engage 7.1.2 inbox message and updates it to `READ`. |
 | `Mapp.inAppMarkAsUnRead(templateId, eventId)` | Android no-op. | Android fetches the inbox message and updates it to `UNREAD`. |
 | `Mapp.inAppMarkAsDeleted(templateId, eventId)` | Android no-op. | Android fetches the inbox message and updates it to `DELETED`. |
-| `Mapp.engage(...)` | iOS JavaScript called the private native `autoengage` and `engageInapp` methods separately. | All platforms use the public native `engage` entry point. On iOS it still initializes both push and in-app, using `AppoxeeConfig.plist` as the credential source of truth. |
+| `Mapp.engage(...)` | iOS JavaScript called the private native `autoengage` and `engageInapp` methods separately, and Android engagement returned before its main-thread task completed. | All platforms use an awaitable native engagement entry point. Await it before calling singleton-dependent APIs. On iOS it still initializes both push and in-app, using `AppoxeeConfig.plist` as the credential source of truth. |
 | iOS event listeners | Events emitted before a JavaScript listener was attached were dropped. | Up to 50 cold-start events are buffered and delivered after a listener attaches. Consumers should tolerate receiving an initial queued event. |
 
 For the Android inbox methods, `eventId` remains accepted for source compatibility but Mapp Engage 7.1.2 identifies and fetches the message using `templateId`.

package/Mapp.js

@@ -127,7 +127,7 @@ export class Mapp {
     server: string,
     appID: string,
     tenantID: string
-  ) {
+  ): Promise<boolean> {
     return RNMappPluginModule.engage(
       sdkKey,
       googleProjectId,
@@ -163,10 +163,22 @@ export class Mapp {
    * @return {Promise.<boolean>} A promise with the result.
    */
   static onInitCompletedListener(): Promise<boolean> {
-    if (Platform.OS == "android") {
+    if (Platform.OS === "android") {
       return RNMappPluginModule.onInitCompletedListener();
     }
-    return null;
+
+    return RNMappPluginModule.isReady().then((ready) => {
+      if (ready) {
+        return true;
+      }
+
+      return new Promise((resolve) => {
+        const subscription = EventEmitter.addListener(IOS_INIT, () => {
+          subscription.remove();
+          resolve(true);
+        });
+      });
+    });
   }
 
   /**

package/README.md

@@ -88,9 +88,11 @@ const subscription = events.addListener('com.mapp.deep_link_received', event =>
   // Route the deep link.
 });
 
-Mapp.engage('ANDROID_SDK_KEY', 'FCM_PROJECT_ID', 'EMC', 'APP_ID', 'TENANT_ID');
+await Mapp.engage('ANDROID_SDK_KEY', 'FCM_PROJECT_ID', 'EMC', 'APP_ID', 'TENANT_ID');
 ```
 
+Always await `Mapp.engage(...)` before calling APIs that use the native Mapp singleton. The promise resolves after native engagement and bridge setup complete; use `Mapp.onInitCompletedListener()` or `Mapp.isReady()` when a feature specifically requires the SDK's later ready state.
+
 ### Android push ownership
 
 `pushHandling: "mapp"` is the default. It requires `expo.android.googleServicesFile` and retains `com.reactlibrary.MessageService` as the sole normal-priority Mapp FCM callback owner. The config plugin removes the Mapp SDK v7 service (`com.appoxee.shared.MappMessagingService`) from the merged app manifest.
@@ -160,7 +162,7 @@ Basic usage:
 ```js
 import { Mapp } from 'react-native-mapp-plugin';
 
-Mapp.engage('SDK_KEY', 'FCM_PROJECT_ID', 'EMC', 'APP_ID', 'TENANT_ID');
+await Mapp.engage('SDK_KEY', 'FCM_PROJECT_ID', 'EMC', 'APP_ID', 'TENANT_ID');
 ```
 
 See the [Mapp integration documentation](https://mapp-wiki.atlassian.net/wiki/spaces/MIC/pages/1154875400/React+Native+Integration+for+Mapp+Cloud) for the full JavaScript API and native Mapp configuration values.

package/android/src/main/java/com/reactlibrary/MappEngagementDispatcher.java

@@ -22,14 +22,40 @@ final class MappEngagementDispatcher {
 
     private MappEngagementDispatcher() {}
 
+    interface EngagementCallback {
+        void onSuccess();
+        void onFailure(@NonNull Exception error);
+    }
+
     static void engageAsync(
             @NonNull Application application,
             @Nullable AppoxeeOptions options,
             @Nullable Runnable afterEngage
+    ) {
+        engageAsync(application, options, afterEngage, null);
+    }
+
+    static void engageAsync(
+            @NonNull Application application,
+            @Nullable AppoxeeOptions options,
+            @Nullable Runnable afterEngage,
+            @Nullable EngagementCallback callback
     ) {
         Runnable operation = () -> {
-            if (engageNow(application, options) && afterEngage != null) {
-                afterEngage.run();
+            try {
+                Appoxee.engage(application, options);
+                if (afterEngage != null) {
+                    afterEngage.run();
+                }
+            } catch (Exception error) {
+                Log.e(TAG, "Mapp initialization failed", error);
+                if (callback != null) {
+                    callback.onFailure(error);
+                }
+                return;
+            }
+            if (callback != null) {
+                callback.onSuccess();
             }
         };
         if (Looper.myLooper() == Looper.getMainLooper()) {
@@ -37,7 +63,13 @@ final class MappEngagementDispatcher {
             return;
         }
         if (!new Handler(Looper.getMainLooper()).post(operation)) {
-            Log.e(TAG, "Unable to post Mapp initialization to the main looper");
+            IllegalStateException error = new IllegalStateException(
+                    "Unable to post Mapp initialization to the main looper"
+            );
+            Log.e(TAG, error.getMessage(), error);
+            if (callback != null) {
+                callback.onFailure(error);
+            }
         }
     }
 
@@ -94,7 +126,7 @@ final class MappEngagementDispatcher {
         try {
             Appoxee.engage(application, options);
             return true;
-        } catch (RuntimeException error) {
+        } catch (Exception error) {
             Log.e(TAG, "Mapp initialization failed", error);
             return false;
         }

package/android/src/main/java/com/reactlibrary/NativeRNMappPluginModuleSpec.java

@@ -76,7 +76,7 @@ public abstract class NativeRNMappPluginModuleSpec extends ReactContextBaseJavaM
 
   @ReactMethod
   @DoNotStrip
-  public abstract void engage(String sdkKey, String googleProjectId, String server, String appID, String tenantID);
+  public abstract void engage(String sdkKey, String googleProjectId, String server, String appID, String tenantID, Promise promise);
 
   @ReactMethod
   @DoNotStrip

package/android/src/main/java/com/reactlibrary/RNMappPluginModule.java

@@ -384,19 +384,42 @@ public class RNMappPluginModule extends NativeRNMappPluginModuleSpec implements
     }
 
     @ReactMethod
-    public void engage(String sdkKey, String googleProjectId, String server, String appID, String tenantID) {
-        AppoxeeOptions opt = createOptions(server, sdkKey, appID, tenantID);
-        opt.setNotificationMode(NotificationMode.BACKGROUND_AND_FOREGROUND);
+    public void engage(String sdkKey, String googleProjectId, String server, String appID,
+                       String tenantID, Promise promise) {
+        final AppoxeeOptions opt;
+        try {
+            opt = createOptions(server, sdkKey, appID, tenantID);
+            opt.setNotificationMode(NotificationMode.BACKGROUND_AND_FOREGROUND);
+        } catch (RuntimeException error) {
+            promise.reject("MAPP_ENGAGE_INVALID_CONFIGURATION", error.getMessage(), error);
+            return;
+        }
 
-        MappEngagementDispatcher.engageAsync(Objects.requireNonNull(application), opt, () -> {
-            Appoxee.instance().subscribe(new AppoxeeObserver() {
-                @Override
-                public void onReadyStatusChanged(boolean status, MappResult<DevicePayload> result) {
+        MappEngagementDispatcher.engageAsync(
+                Objects.requireNonNull(application),
+                opt,
+                this::configureAfterEngage,
+                new MappEngagementDispatcher.EngagementCallback() {
+                    @Override
+                    public void onSuccess() {
+                        promise.resolve(true);
+                    }
+
+                    @Override
+                    public void onFailure(@NonNull Exception error) {
+                        promise.reject("MAPP_ENGAGE_FAILED", "Mapp initialization failed", error);
+                    }
                 }
-            });
+        );
+    }
 
-            Appoxee.instance().setPushBroadcast(MyPushBroadcastReceiver.class);
+    private void configureAfterEngage() {
+        Appoxee.instance().subscribe(new AppoxeeObserver() {
+            @Override
+            public void onReadyStatusChanged(boolean status, MappResult<DevicePayload> result) {
+            }
         });
+        Appoxee.instance().setPushBroadcast(MyPushBroadcastReceiver.class);
     }
 
     @ReactMethod

package/android/src/main/jni/RNMappPlugin-generated.cpp

@@ -64,7 +64,7 @@ static facebook::jsi::Value __hostFunction_NativeRNMappPluginModuleSpecJSI_engag
 
 static facebook::jsi::Value __hostFunction_NativeRNMappPluginModuleSpecJSI_engage(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
   static jmethodID cachedMethodId = nullptr;
-  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, VoidKind, "engage", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V", args, count, cachedMethodId);
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "engage", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
 }
 
 static facebook::jsi::Value __hostFunction_NativeRNMappPluginModuleSpecJSI_engageTestServer(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {

package/android/src/main/jni/react/renderer/components/RNMappPlugin/RNMappPluginJSI.h

@@ -154,12 +154,12 @@ private:
     static_assert(
       bridging::getParameterCount(&T::engage) == 6,
       "Expected engage(...) to have 6 parameters");
-    bridging::callFromJs<void>(rt, &T::engage,  static_cast<NativeRNMappPluginModuleCxxSpec*>(&turboModule)->jsInvoker_, static_cast<T*>(&turboModule),
+    return bridging::callFromJs<jsi::Value>(rt, &T::engage,  static_cast<NativeRNMappPluginModuleCxxSpec*>(&turboModule)->jsInvoker_, static_cast<T*>(&turboModule),
       count <= 0 ? throw jsi::JSError(rt, "Expected argument in position 0 to be passed") : args[0].asString(rt),
       count <= 1 ? throw jsi::JSError(rt, "Expected argument in position 1 to be passed") : args[1].asString(rt),
       count <= 2 ? throw jsi::JSError(rt, "Expected argument in position 2 to be passed") : args[2].asString(rt),
       count <= 3 ? throw jsi::JSError(rt, "Expected argument in position 3 to be passed") : args[3].asString(rt),
-      count <= 4 ? throw jsi::JSError(rt, "Expected argument in position 4 to be passed") : args[4].asString(rt));return jsi::Value::undefined();
+      count <= 4 ? throw jsi::JSError(rt, "Expected argument in position 4 to be passed") : args[4].asString(rt));
   }
 
   static jsi::Value __engageTestServer(jsi::Runtime &rt, TurboModule &turboModule, const jsi::Value* args, size_t count) {

package/ios/RNMappPluginModule.mm

@@ -94,7 +94,7 @@ RCT_EXPORT_METHOD(getToken:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRej
 RCT_EXPORT_METHOD(engage2) {}
 
 RCT_EXPORT_METHOD(engageTestServer:(NSString *)cepUrl sdkKey:(NSString *)sdkKey googleProjectId:(NSString *)projectId server:(NSString *)server appID:(NSString *)appID tenantID:(NSString *)tenantID) {
-    [self engage:sdkKey googleProjectId:projectId server:server appID:appID tenantID:tenantID];
+    [self performEngage:sdkKey googleProjectId:projectId server:server appID:appID tenantID:tenantID];
 }
 
 RCT_EXPORT_METHOD(onInitCompletedListener:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject) {
@@ -131,13 +131,33 @@ RCT_EXPORT_METHOD(removeAndroidListeners:(NSInteger)count) {}
 
 #pragma mark Exported methods - Notifications
 
-RCT_EXPORT_METHOD(engage: (NSString *)sdkKey googleProjectId: (NSString *)projectId server:(NSString *)server appID:(NSString *)appID tenantID:(NSString *)tenantID) {
+- (void)performEngage:(NSString *)sdkKey
+      googleProjectId:(NSString *)projectId
+               server:(NSString *)server
+                appID:(NSString *)appID
+             tenantID:(NSString *)tenantID {
     SERVER serv = [self getServerKeyFor:server];
     [[Appoxee shared] engageAndAutoIntegrateWithLaunchOptions:nil andDelegate:[RNMappEventEmmiter shared] with:serv];
     [[Appoxee shared] addObserver: [RNMappEventEmmiter shared] forKeyPath:@"isReady" options:NSKeyValueObservingOptionNew context:nil];
     [[AppoxeeInapp shared] engageWithDelegate:[RNMappEventEmmiter shared] with:[self getInappServerKeyFor:server]];
 }
 
+RCT_EXPORT_METHOD(engage:(NSString *)sdkKey
+                  googleProjectId:(NSString *)projectId
+                  server:(NSString *)server
+                  appID:(NSString *)appID
+                  tenantID:(NSString *)tenantID
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    @try {
+        [self performEngage:sdkKey googleProjectId:projectId server:server appID:appID tenantID:tenantID];
+        resolve(@YES);
+    } @catch (NSException *exception) {
+        NSString *message = exception.reason ?: @"Mapp initialization failed";
+        reject(@"MAPP_ENGAGE_FAILED", message, nil);
+    }
+}
+
 RCT_EXPORT_METHOD(getAlias:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject) {
     [[Appoxee shared] getDeviceAliasWithCompletionHandler:^(NSError * _Nullable appoxeeError, id  _Nullable data) {
         if (appoxeeError == nil && data != nil) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-mapp-plugin",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Mapp SDK for React Native.",
   "main": "index.js",
   "files": [
@@ -99,7 +99,12 @@
     ],
     "transform": {
       "^.+\\.js$": "babel-jest",
-      "^.+\\.ts$": ["ts-jest", { "tsconfig": "plugin/tsconfig.json" }]
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "tsconfig": "plugin/tsconfig.json"
+        }
+      ]
     },
     "moduleNameMapper": {
       "^react-native$": "<rootDir>/__mocks__/react-native.js"

package/specs/NativeRNMappPluginModule.js

@@ -16,7 +16,7 @@ export interface Spec extends TurboModule {
   getAlias(): Promise<string>;
   /** @deprecated Use engage(...). */
   engage2(): void;
-  engage(sdkKey: string, googleProjectId: string, server: string, appID: string, tenantID: string): void;
+  engage(sdkKey: string, googleProjectId: string, server: string, appID: string, tenantID: string): Promise<boolean>;
   engageTestServer(cepURl: string, sdkKey: string, googleProjectId: string, server: string, appID: string, tenantID: string): void;
   onInitCompletedListener(): Promise<boolean>;
   isReady(): Promise<boolean>;