SDK-478 resolve init promise immediately on iOS SDK, matching Android SDK (#869)

* ✨ Updated the SDK initialize method

* 🧪 Increased the tests wait time to avoid flakyness from CI

* docs: clarify bridge fix and InAppManager-vs-init distinction in CHANGELOG

Spells out what the iOS bridge actually fixed, that IterableAPI.initialize is
sync and non-failable, and that the previous user-visible error came from the
in-app messages fetch retry budget, not from SDK initialization.

Author: joaodordio

CHANGELOG.md

@@ -1,5 +1,12 @@
 ## Unreleased
 
+### Fixes
+- Fixed the React Native bridge contract for `Iterable.initialize` on iOS.
+  - The iOS bridge now calls the synchronous native initializer (`IterableAPI.initialize`) and resolves the JS promise immediately, matching the Android bridge which has always behaved this way.
+  - Previously, the iOS bridge wired the JS promise to the `initialize2(callback:)` overload, whose callback fires when the first in-app messages fetch settles, not when the SDK is ready to use. That callback is an `InAppManager.start()` signal and has nothing to do with whether `IterableAPI.initialize` succeeded.
+  - On iOS, `IterableAPI.initialize(...)` is synchronous, non-failable, and returns `Void`. The native SDK is fully usable the moment it returns. There is no init-error channel to await on the native side, and JS callers should not treat the promise as one. `await Iterable.initialize(...)` is supported for API symmetry but does not gate SDK readiness on any async work.
+  - The user-visible symptom of the old contract was a multi-second to multi-minute hang on the JS promise under JWT or network friction, surfaced as an init failure even though the SDK had already initialized successfully. The error originated in the in-app messages fetch retry budget, not in initialization.
+
 ### Updates
 
 - Added `Iterable.registerDeviceToken(token)` to re-enable push for the current device.
@@ -13,7 +20,6 @@
 - Updated RN compatibility to 0.85
 
 ## 3.0.0
-
 ### Updates
 
 - Added embedded messaging functionality. This includes the ability to:

ios/RNIterableAPI/ReactIterableAPI.swift

@@ -668,24 +668,40 @@ import React
       name: Notification.Name.iterableInboxChanged, object: nil)
 
     DispatchQueue.main.async {
-      IterableAPI.initialize2(
-        apiKey: apiKey,
-        launchOptions: launchOptions,
-        config: iterableConfig,
-        apiEndPointOverride: apiEndPointOverride
-      ) { result in
-        resolver(result)
+      // The native iOS SDK is fully usable the moment IterableAPI.initialize
+      // returns. The legacy initialize2(callback:) overload fires its callback
+      // only after inAppManager.start() resolves the first in-app messages
+      // fetch, which can take 60s+ under any auth or network friction and
+      // blocks the JS promise on a signal that does not actually represent
+      // "SDK ready". Android's RNIterableAPIModuleImpl.initializeWithApiKey
+      // resolves promise.resolve(true) immediately after sync init - this
+      // brings iOS to parity. See SDK-478.
+      if let apiEndPointOverride = apiEndPointOverride {
+        IterableAPI.initialize2(
+          apiKey: apiKey,
+          launchOptions: launchOptions,
+          config: iterableConfig,
+          apiEndPointOverride: apiEndPointOverride
+        )
+      } else {
+        IterableAPI.initialize(
+          apiKey: apiKey,
+          launchOptions: launchOptions,
+          config: iterableConfig
+        )
       }
 
       IterableAPI.setDeviceAttribute(name: "reactNativeSDKVersion", value: version)
-      
+
       // Add embedded update listener if any callback is present
       let onEmbeddedMessageUpdatePresent = configDict["onEmbeddedMessageUpdatePresent"] as? Bool ?? false
       let onEmbeddedMessagingDisabledPresent = configDict["onEmbeddedMessagingDisabledPresent"] as? Bool ?? false
-      
+
       if onEmbeddedMessageUpdatePresent || onEmbeddedMessagingDisabledPresent {
         IterableAPI.embeddedManager.addUpdateListener(self)
       }
+
+      resolver(true)
     }
   }
 

src/core/classes/IterableApi.test.ts

@@ -70,6 +70,24 @@ describe('IterableApi', () => {
       );
       expect(result).toBe(true);
     });
+
+    // SDK-478: the bridge contract is "resolve true immediately after calling
+    // sync IterableAPI.initialize on the native side". The JS layer is a pure
+    // passthrough. This pins that the JS code does not add an await on any
+    // additional async work between the native call and the returned promise.
+    // Regression guard for the 2021 contract drift that gated the JS promise
+    // on the first in-app messages fetch (commit 4c357126).
+    it('resolves promptly without awaiting any additional async work', async () => {
+      MockRNIterableAPI.initializeWithApiKey.mockResolvedValueOnce(true);
+      const startedAt = Date.now();
+      const result = await IterableApi.initializeWithApiKey('test-api-key', {
+        config: new IterableConfig(),
+        version: '1.0.0',
+      });
+      const elapsedMs = Date.now() - startedAt;
+      expect(result).toBe(true);
+      expect(elapsedMs).toBeLessThan(250);
+    });
   });
 
   describe('initialize2WithApiKey', () => {
@@ -119,6 +137,22 @@ describe('IterableApi', () => {
       );
       expect(result).toBe(true);
     });
+
+    // SDK-478: same contract as initializeWithApiKey above. initialize2 is only
+    // used for staging/test endpoint overrides; its JS-side behavior is still
+    // "resolve immediately with whatever native returns" - no additional waits.
+    it('resolves promptly without awaiting any additional async work', async () => {
+      MockRNIterableAPI.initialize2WithApiKey.mockResolvedValueOnce(true);
+      const startedAt = Date.now();
+      const result = await IterableApi.initialize2WithApiKey('test-api-key', {
+        config: new IterableConfig(),
+        version: '1.0.0',
+        apiEndPoint: 'https://api.staging.iterable.com',
+      });
+      const elapsedMs = Date.now() - startedAt;
+      expect(result).toBe(true);
+      expect(elapsedMs).toBeLessThan(250);
+    });
   });
 
   // ====================================================== //