feat: add pushOpenHandler callback for push notification opens (#71)

Add a new pushOpenHandler callback to IterableConfig that fires when a
push notification is opened, providing the raw push payload data. This
eliminates the need for polling getLastPushPayload() and gives apps
reliable access to push notification data on user interaction.

The handler fires for push-originated URL actions, custom actions, and
cold-start push opens without actions.

https://claude.ai/code/session_01UHEH39nQzFoTkCh7EzShqn

Author: claude

android/src/main/java/com/iterable/reactnative/RNIterableAPIModuleImpl.java

@@ -69,6 +69,8 @@ public class RNIterableAPIModuleImpl implements IterableUrlHandler, IterableCust
 
     private final InboxSessionManager sessionManager = new InboxSessionManager();
 
+    private boolean pushOpenHandlerPresent = false;
+
     public RNIterableAPIModuleImpl(ReactApplicationContext reactContext) {
         this.reactContext = reactContext;
     }
@@ -93,6 +95,8 @@ public void initializeWithApiKey(String apiKey, ReadableMap configReadableMap, S
             configBuilder.setAuthHandler(this);
         }
 
+        pushOpenHandlerPresent = configReadableMap.hasKey("pushOpenHandlerPresent") && configReadableMap.getBoolean("pushOpenHandlerPresent");
+
         // Check if embedded messaging is enabled before building config
         boolean enableEmbeddedMessaging = configReadableMap.hasKey("enableEmbeddedMessaging") && configReadableMap.getBoolean("enableEmbeddedMessaging");
 
@@ -136,6 +140,9 @@ public void initializeWithApiKey(String apiKey, ReadableMap configReadableMap, S
             IterableApi.getInstance().getEmbeddedManager().addUpdateListener(this);
         }
 
+        // Emit push open event for cold-start push opens
+        emitPushOpenIfPresent();
+
         // MOB-10421: Figure out what the error cases are and handle them appropriately
         // This is just here to match the TS types and let the JS thread know when we are done initializing
         promise.resolve(true);
@@ -161,6 +168,8 @@ public void initialize2WithApiKey(String apiKey, ReadableMap configReadableMap,
             configBuilder.setAuthHandler(this);
         }
 
+        pushOpenHandlerPresent = configReadableMap.hasKey("pushOpenHandlerPresent") && configReadableMap.getBoolean("pushOpenHandlerPresent");
+
         // NOTE: There does not seem to be a way to set the API endpoint
         // override in the Android SDK.  Check with @Ayyanchira and @evantk91 to
         // see what the best approach is.
@@ -208,6 +217,9 @@ public void initialize2WithApiKey(String apiKey, ReadableMap configReadableMap,
             IterableApi.getInstance().getEmbeddedManager().addUpdateListener(this);
         }
 
+        // Emit push open event for cold-start push opens
+        emitPushOpenIfPresent();
+
         // MOB-10421: Figure out what the error cases are and handle them appropriately
         // This is just here to match the TS types and let the JS thread know when we are done initializing
         promise.resolve(true);
@@ -596,6 +608,12 @@ public boolean handleIterableCustomAction(@NonNull IterableAction action, @NonNu
         } catch (JSONException e) {
             IterableLogger.e(TAG, "Failed handling custom action");
         }
+
+        // Also emit push open event when the custom action originated from a push notification
+        if (pushOpenHandlerPresent && actionContext.source.ordinal() == 0 /* PUSH */) {
+            emitPushOpenIfPresent();
+        }
+
         // The Android SDK will not bring the app into focus is this is `true`. It still respects the `openApp` bool flag.
         return false;
     }
@@ -635,6 +653,12 @@ public boolean handleIterableURL(@NonNull Uri uri, @NonNull IterableActionContex
         } catch (JSONException e) {
             IterableLogger.e(TAG, e.getLocalizedMessage());
         }
+
+        // Also emit push open event when the URL action originated from a push notification
+        if (pushOpenHandlerPresent && actionContext.source.ordinal() == 0 /* PUSH */) {
+            emitPushOpenIfPresent();
+        }
+
         return true;
     }
 
@@ -701,6 +725,18 @@ public void sendEvent(@NonNull String eventName, @Nullable Object eventData) {
         reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class).emit(eventName, eventData);
     }
 
+    private void emitPushOpenIfPresent() {
+        if (!pushOpenHandlerPresent) {
+            return;
+        }
+        Bundle payloadData = IterableApi.getInstance().getPayloadData();
+        if (payloadData != null) {
+            WritableMap eventData = Arguments.createMap();
+            eventData.putMap("pushPayload", Arguments.fromBundle(payloadData));
+            sendEvent(EventName.handlePushOpenCalled.name(), eventData);
+        }
+    }
+
     @Override
     public void onInboxUpdated() {
         sendEvent(EventName.receivedIterableInboxChanged.name(), null);
@@ -809,6 +845,7 @@ enum EventName {
   handleEmbeddedMessageUpdateCalled,
   handleEmbeddedMessagingDisabledCalled,
   handleInAppCalled,
+  handlePushOpenCalled,
   handleUrlCalled,
   receivedIterableEmbeddedMessagesChanged,
   receivedIterableInboxChanged

ios/RNIterableAPI/ReactIterableAPI.swift

@@ -35,6 +35,7 @@ import React
     case handleAuthFailureCalled
     case handleEmbeddedMessageUpdateCalled
     case handleEmbeddedMessagingDisabledCalled
+    case handlePushOpenCalled
   }
 
   @objc public static var supportedEvents: [String] {
@@ -599,6 +600,8 @@ import React
 
   private let inboxSessionManager = InboxSessionManager()
 
+  private var pushOpenHandlerPresent = false
+
   @objc func initialize(
     withApiKey apiKey: String,
     config configDict: NSDictionary,
@@ -644,6 +647,8 @@ import React
       self, selector: #selector(receivedIterableInboxChanged),
       name: Notification.Name.iterableInboxChanged, object: nil)
 
+    self.pushOpenHandlerPresent = configDict["pushOpenHandlerPresent"] as? Bool ?? false
+
     DispatchQueue.main.async {
       IterableAPI.initialize2(
         apiKey: apiKey,
@@ -655,14 +660,21 @@ import React
       }
 
       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)
       }
+
+      // Emit push open event for cold-start push opens
+      if self.pushOpenHandlerPresent, let pushPayload = IterableAPI.lastPushPayload {
+        self.delegate?.sendEvent(
+          withName: EventName.handlePushOpenCalled.rawValue,
+          body: ["pushPayload": pushPayload])
+      }
     }
   }
 
@@ -710,6 +722,14 @@ extension ReactIterableAPI: IterableURLDelegate {
         "url": url.absoluteString,
         "context": contextDict,
       ] as [String: Any])
+
+    // Also emit push open event when the URL action originated from a push notification
+    if pushOpenHandlerPresent && context.source == .push {
+      let pushPayload = IterableAPI.lastPushPayload ?? [:]
+      delegate?.sendEvent(
+        withName: EventName.handlePushOpenCalled.rawValue,
+        body: ["pushPayload": pushPayload])
+    }
     return true
   }
 
@@ -749,6 +769,14 @@ extension ReactIterableAPI: IterableCustomActionDelegate {
         "action": actionDict,
         "context": contextDict,
       ])
+
+    // Also emit push open event when the custom action originated from a push notification
+    if pushOpenHandlerPresent && context.source == .push {
+      let pushPayload = IterableAPI.lastPushPayload ?? [:]
+      delegate?.sendEvent(
+        withName: EventName.handlePushOpenCalled.rawValue,
+        body: ["pushPayload": pushPayload])
+    }
     return true
   }
 }

src/core/classes/Iterable.test.ts

@@ -321,6 +321,7 @@ describe('Iterable', () => {
       expect(config.logLevel).toBe(IterableLogLevel.debug);
       expect(config.logReactNativeSdkCalls).toBe(true);
       expect(config.pushIntegrationName).toBe(undefined);
+      expect(config.pushOpenHandler).toBe(undefined);
       expect(config.urlHandler).toBe(undefined);
       expect(config.useInMemoryStorageForInApps).toBe(false);
       const configDict = config.toDict();
@@ -337,11 +338,59 @@ describe('Iterable', () => {
       expect(configDict.inAppHandlerPresent).toBe(false);
       expect(configDict.logLevel).toBe(IterableLogLevel.debug);
       expect(configDict.pushIntegrationName).toBe(undefined);
+      expect(configDict.pushOpenHandlerPresent).toBe(false);
       expect(configDict.urlHandlerPresent).toBe(false);
       expect(configDict.useInMemoryStorageForInApps).toBe(false);
     });
   });
 
+  describe('pushOpenHandler', () => {
+    it('should be called with the push payload when handlePushOpenCalled event is emitted', () => {
+      // sets up event emitter
+      const nativeEmitter = new NativeEventEmitter();
+      nativeEmitter.removeAllListeners(IterableEventName.handlePushOpenCalled);
+      // sets up config file and pushOpenHandler function
+      const config = new IterableConfig();
+      config.logReactNativeSdkCalls = false;
+      config.pushOpenHandler = jest.fn(
+        (_pushPayload: Record<string, unknown>) => {}
+      );
+      // initialize Iterable object
+      Iterable.initialize('apiKey', config);
+      // GIVEN a push payload
+      const expectedPayload = {
+        campaignId: 123,
+        templateId: 456,
+        customKey: 'customValue',
+      };
+      const dict = { pushPayload: expectedPayload };
+      // WHEN handlePushOpenCalled event is emitted
+      nativeEmitter.emit(IterableEventName.handlePushOpenCalled, dict);
+      // THEN pushOpenHandler is called with expected payload
+      expect(config.pushOpenHandler).toBeCalledWith(expectedPayload);
+    });
+
+    it('should pass empty object when pushPayload is undefined', () => {
+      // sets up event emitter
+      const nativeEmitter = new NativeEventEmitter();
+      nativeEmitter.removeAllListeners(IterableEventName.handlePushOpenCalled);
+      // sets up config file and pushOpenHandler function
+      const config = new IterableConfig();
+      config.logReactNativeSdkCalls = false;
+      config.pushOpenHandler = jest.fn(
+        (_pushPayload: Record<string, unknown>) => {}
+      );
+      // initialize Iterable object
+      Iterable.initialize('apiKey', config);
+      // GIVEN no push payload in the event
+      const dict = {};
+      // WHEN handlePushOpenCalled event is emitted
+      nativeEmitter.emit(IterableEventName.handlePushOpenCalled, dict);
+      // THEN pushOpenHandler is called with empty object
+      expect(config.pushOpenHandler).toBeCalledWith({});
+    });
+  });
+
   describe('urlHandler', () => {
     it('should open the url when canOpenURL returns true and urlHandler returns false', async () => {
       // sets up event emitter

src/core/classes/Iterable.ts

@@ -956,6 +956,9 @@ export class Iterable {
     RNEventEmitter.removeAllListeners(
       IterableEventName.handleEmbeddedMessagingDisabledCalled
     );
+    RNEventEmitter.removeAllListeners(
+      IterableEventName.handlePushOpenCalled
+    );
   }
 
   /**
@@ -1109,6 +1112,16 @@ export class Iterable {
         );
       }
     }
+
+    if (Iterable.savedConfig.pushOpenHandler) {
+      RNEventEmitter.addListener(
+        IterableEventName.handlePushOpenCalled,
+        (dict) => {
+          const pushPayload = dict.pushPayload ?? {};
+          Iterable.savedConfig.pushOpenHandler?.(pushPayload);
+        }
+      );
+    }
   }
 
   /**

src/core/classes/IterableConfig.ts

@@ -375,6 +375,31 @@ export class IterableConfig {
    */
   onEmbeddedMessagingDisabled?: () => void;
 
+  /**
+   * A callback function that is called when a push notification is opened by the user.
+   *
+   * This handler provides the raw push notification payload, giving you access
+   * to all custom data fields sent with the notification. It fires for all
+   * push-originated interactions, regardless of whether the notification has
+   * a URL action, custom action, or no action at all.
+   *
+   * @param pushPayload - The raw push notification payload as a dictionary.
+   *
+   * @example
+   * ```typescript
+   * const config = new IterableConfig();
+   * config.pushOpenHandler = (pushPayload) => {
+   *   console.log('Push notification opened:', pushPayload);
+   *   // Navigate based on custom data in the payload
+   *   if (pushPayload.screen) {
+   *     navigation.navigate(pushPayload.screen);
+   *   }
+   * };
+   * Iterable.initialize('<YOUR_API_KEY>', config);
+   * ```
+   */
+  pushOpenHandler?: (pushPayload: Record<string, unknown>) => void;
+
   /**
    * Converts the IterableConfig instance to a dictionary object.
    *
@@ -428,6 +453,11 @@ export class IterableConfig {
       // eslint-disable-next-line eqeqeq
       onEmbeddedMessagingDisabledPresent:
         this.onEmbeddedMessagingDisabled != undefined,
+      /**
+       * A boolean indicating if a push open handler is present.
+       */
+      // eslint-disable-next-line eqeqeq
+      pushOpenHandlerPresent: this.pushOpenHandler != undefined,
       /** The log level for the SDK. */
       logLevel: this.logLevel,
       expiringAuthTokenRefreshPeriod: this.expiringAuthTokenRefreshPeriod,

src/core/enums/IterableEventName.ts

@@ -23,4 +23,6 @@ export enum IterableEventName {
   handleEmbeddedMessageUpdateCalled = 'handleEmbeddedMessageUpdateCalled',
   /** Event that fires when embedded messaging is disabled */
   handleEmbeddedMessagingDisabledCalled = 'handleEmbeddedMessagingDisabledCalled',
+  /** Event that fires when a push notification is opened */
+  handlePushOpenCalled = 'handlePushOpenCalled',
 }