Changed for new ENUM type instead of a new handler with similar name to avoid confusion

Author: franco-zalamena-iterable

CHANGELOG.md

@@ -4,7 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
-- Added `IterableInAppDisplayHandler` for real-time, per-message control over whether the SDK automatically displays an in-app message. Set it via `IterableConfig.Builder.setInAppDisplayHandler()`. Returning `true` from `isAutoDisplayPaused(message)` defers that message so it is reconsidered on a later display pass (rather than being permanently skipped). The handler takes precedence over the global `IterableInAppManager.setAutoDisplayPaused(boolean)` flag.
+- Added a `DEFER` response to `IterableInAppHandler.InAppResponse`, returned from `onNewInApp(message)`. Unlike `SKIP` (which permanently drops the message), `DEFER` leaves the message pending so the SDK reconsiders it on a later display pass (next foreground, sync, or newly arrived message). Use it for temporary, per-message suppression — for example while a splash screen is showing. Existing handlers returning `SHOW`/`SKIP` are unaffected.
 - Added `IterableInAppManager.resumeInAppDisplay()` so apps can prompt the SDK to re-evaluate pending in-app messages once they become ready to display (e.g. after a splash screen is dismissed), without waiting for the next foreground/sync trigger.
 - Notification small-icon resolution now falls back through standard conventions — the Firebase `com.google.firebase.messaging.default_notification_icon` meta-data, `@drawable/notification_icon` (Expo / React Native), and `@drawable/ic_notification` — before defaulting to the app launcher icon. This fixes white-square notification icons on Android 5.0+ for apps that configure their icon through these conventions but don't set `iterable_notification_icon`.
 - Added support for in-app messages in fully Jetpack Compose apps using a Dialog-based renderer (`IterableInAppDialogNotification`), removing the requirement for a `FragmentActivity`.
@@ -20,6 +20,23 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Fixed
 - Fixed a `TransactionTooLargeException` crash when displaying in-app messages with oversized HTML payloads. The HTML is no longer serialized into the fragment's saved instance state; it is reloaded from storage on recreation. In-apps with missing HTML now dismiss gracefully without registering tracking events, and a warning is logged for HTML payloads exceeding the recommended size.
 
+### Migration guide
+**No action required.** Existing `IterableInAppHandler` implementations returning `SHOW`/`SKIP` are unaffected.
+
+To suppress an in-app temporarily (e.g. during a splash screen), return the new `DEFER` instead of `SKIP` — the message stays pending and is re-offered on a later display pass:
+
+```java
+new IterableConfig.Builder().setInAppHandler(message ->
+    appIsShowingSplashScreen()
+        ? IterableInAppHandler.InAppResponse.DEFER
+        : IterableInAppHandler.InAppResponse.SHOW
+).build();
+```
+
+Once ready, call `IterableApi.getInstance().getInAppManager().resumeInAppDisplay()` to re-check pending messages immediately instead of waiting for the next foreground/sync.
+
+> **Kotlin:** add a `DEFER` branch to any exhaustive `when` over `InAppResponse`.
+
 ## [3.8.0]
 ### Added
 - New `IterableInAppDisplayMode` enum to control how in-app messages interact with system bars. Configure via `IterableConfig.Builder.setInAppDisplayMode()`:

iterableapi/src/main/java/com/iterable/iterableapi/IterableApi.java

@@ -828,7 +828,6 @@ public static void initialize(@NonNull Context context, @NonNull String apiKey,
             sharedInstance.inAppManager = new IterableInAppManager(
                     sharedInstance,
                     sharedInstance.config.inAppHandler,
-                    sharedInstance.config.inAppDisplayHandler,
                     sharedInstance.config.inAppDisplayInterval,
                     sharedInstance.config.useInMemoryStorageForInApps);
         }

iterableapi/src/main/java/com/iterable/iterableapi/IterableConfig.java

@@ -50,13 +50,6 @@ public class IterableConfig {
      */
     final IterableInAppHandler inAppHandler;
 
-    /**
-     * Optional handler that gives the app real-time, per-message control over whether an in-app
-     * message should be displayed automatically. Takes precedence over the global auto-display pause.
-     */
-    @Nullable
-    final IterableInAppDisplayHandler inAppDisplayHandler;
-
     /**
      * The number of seconds to wait before showing the next in-app message, if there are multiple
      * messages in the queue
@@ -178,7 +171,6 @@ private IterableConfig(Builder builder) {
         checkForDeferredDeeplink = builder.checkForDeferredDeeplink;
         logLevel = builder.logLevel;
         inAppHandler = builder.inAppHandler;
-        inAppDisplayHandler = builder.inAppDisplayHandler;
         inAppDisplayInterval = builder.inAppDisplayInterval;
         authHandler = builder.authHandler;
         expiringAuthTokenRefreshPeriod = builder.expiringAuthTokenRefreshPeriod;
@@ -208,7 +200,6 @@ public static class Builder {
         private boolean checkForDeferredDeeplink;
         private int logLevel = Log.ERROR;
         private IterableInAppHandler inAppHandler = new IterableDefaultInAppHandler();
-        private IterableInAppDisplayHandler inAppDisplayHandler = null;
         private double inAppDisplayInterval = 30.0;
         private IterableAuthHandler authHandler;
         private long expiringAuthTokenRefreshPeriod = 60000L;
@@ -318,20 +309,6 @@ public Builder setInAppHandler(@NonNull IterableInAppHandler inAppHandler) {
             return this;
         }
 
-        /**
-         * Set an in-app display handler for real-time, per-message control over whether an in-app
-         * message should be displayed automatically. Returning {@code true} from
-         * {@link IterableInAppDisplayHandler#isAutoDisplayPaused(IterableInAppMessage)} defers the
-         * message so it is reconsidered on a later display pass. Takes precedence over
-         * {@link IterableInAppManager#setAutoDisplayPaused(boolean)}.
-         * @param inAppDisplayHandler In-app display handler provided by the app
-         */
-        @NonNull
-        public Builder setInAppDisplayHandler(@NonNull IterableInAppDisplayHandler inAppDisplayHandler) {
-            this.inAppDisplayHandler = inAppDisplayHandler;
-            return this;
-        }
-
         /**
          * Set the in-app message display interval: the number of seconds to wait before showing
          * the next in-app message, if there are multiple messages in the queue

iterableapi/src/main/java/com/iterable/iterableapi/IterableInAppDisplayHandler.java

@@ -4,8 +4,16 @@
 
 public interface IterableInAppHandler {
     enum InAppResponse {
+        /** Display the in-app message now. */
         SHOW,
-        SKIP
+        /** Do not display the in-app message; it is marked processed and will not be reconsidered. */
+        SKIP,
+        /**
+         * Do not display the in-app message right now, but leave it pending so the SDK asks again on
+         * a later display pass (e.g. the next foreground, sync, or newly arrived message). Use this
+         * for temporary, per-message suppression — for example while a splash screen is showing.
+         */
+        DEFER
     }
 
     @NonNull

iterableapi/src/main/java/com/iterable/iterableapi/IterableInAppHandler.java

@@ -43,8 +43,6 @@ public interface Listener {
     private final Context context;
     private final IterableInAppStorage storage;
     private final IterableInAppHandler handler;
-    @Nullable
-    private final IterableInAppDisplayHandler displayHandler;
     private final IterableInAppDisplayer displayer;
     private final IterableActivityMonitor activityMonitor;
     private final double inAppDisplayInterval;
@@ -53,10 +51,9 @@ public interface Listener {
     private long lastInAppShown = 0;
     private boolean autoDisplayPaused = false;
 
-    IterableInAppManager(IterableApi iterableApi, IterableInAppHandler handler, @Nullable IterableInAppDisplayHandler displayHandler, double inAppDisplayInterval, boolean useInMemoryStorageForInApps) {
+    IterableInAppManager(IterableApi iterableApi, IterableInAppHandler handler, double inAppDisplayInterval, boolean useInMemoryStorageForInApps) {
         this(iterableApi,
                 handler,
-                displayHandler,
                 inAppDisplayInterval,
                 IterableInAppManager.getInAppStorageModel(iterableApi, useInMemoryStorageForInApps),
                 IterableActivityMonitor.getInstance(),
@@ -66,15 +63,13 @@ public interface Listener {
     @VisibleForTesting
     IterableInAppManager(IterableApi iterableApi,
                          IterableInAppHandler handler,
-                         @Nullable IterableInAppDisplayHandler displayHandler,
                          double inAppDisplayInterval,
                          IterableInAppStorage storage,
                          IterableActivityMonitor activityMonitor,
                          IterableInAppDisplayer displayer) {
         this.api = iterableApi;
         this.context = iterableApi.getMainActivityContext();
         this.handler = handler;
-        this.displayHandler = displayHandler;
         this.inAppDisplayInterval = inAppDisplayInterval;
         this.storage = storage;
         this.displayer = displayer;
@@ -164,12 +159,13 @@ public void setAutoDisplayPaused(boolean paused) {
     /**
      * Ask the SDK to re-evaluate whether a pending in-app message can be displayed now.
      * <p>
-     * Use this when display was deferred via {@link IterableInAppDisplayHandler} (or
-     * {@link #setAutoDisplayPaused(boolean)}) and your app has since become ready to show in-apps —
-     * for example once a splash screen is dismissed and the main UI is visible. The SDK only
-     * re-checks pending messages on its own triggers (foreground, sync, new message); calling this
-     * lets the app prompt a re-check without one of those occurring. This does not change any stored
-     * state; it triggers a single display attempt.
+     * Use this when display was deferred — by returning {@link IterableInAppHandler.InAppResponse#DEFER}
+     * from {@link IterableInAppHandler#onNewInApp(IterableInAppMessage)}, or via
+     * {@link #setAutoDisplayPaused(boolean)} — and your app has since become ready to show in-apps,
+     * for example once a splash screen is dismissed and the main UI is visible. The SDK otherwise
+     * only re-checks pending messages on its own triggers (foreground, sync, new message); calling
+     * this prompts a re-check without one of those occurring. This does not change any stored state;
+     * it triggers a single display attempt.
      */
     public void resumeInAppDisplay() {
         scheduleProcessing();
@@ -413,7 +409,7 @@ public int compare(IterableInAppMessage message1, IterableInAppMessage message2)
     }
 
     private void processMessages() {
-        if (!activityMonitor.isInForeground() || isShowingInApp() || !canShowInAppAfterPrevious()) {
+        if (!activityMonitor.isInForeground() || isShowingInApp() || !canShowInAppAfterPrevious() || isAutoDisplayPaused()) {
             return;
         }
 
@@ -424,12 +420,15 @@ private void processMessages() {
 
         for (IterableInAppMessage message : messagesByPriorityLevel) {
             if (!message.isProcessed() && !message.isConsumed() && message.getTriggerType() == TriggerType.IMMEDIATE && !message.isRead()) {
-                if (isAutoDisplayPaused(message)) {
-                    return;
-                }
                 IterableLogger.d(TAG, "Calling onNewInApp on " + message.getMessageId());
                 InAppResponse response = handler.onNewInApp(message);
                 IterableLogger.d(TAG, "Response: " + response);
+
+                if (response == InAppResponse.DEFER) {
+                    // Leave the message unprocessed so it is reconsidered on a later display pass.
+                    continue;
+                }
+
                 message.setProcessed(true);
 
                 if (message.isJsonOnly()) {
@@ -480,8 +479,8 @@ private boolean canShowInAppAfterPrevious() {
         return getSecondsSinceLastInApp() >= inAppDisplayInterval;
     }
 
-    private boolean isAutoDisplayPaused(IterableInAppMessage message) {
-        return displayHandler != null ? displayHandler.isAutoDisplayPaused(message) : autoDisplayPaused;
+    boolean isAutoDisplayPaused() {
+        return autoDisplayPaused;
     }
 
     private void handleIterableCustomAction(String actionName, IterableInAppMessage message) {

iterableapi/src/main/java/com/iterable/iterableapi/IterableInAppManager.java

@@ -38,7 +38,7 @@ public class IterableInAppManagerSyncTest extends BaseTest {
     @Before
     public void setUp() throws Exception {
         MockitoAnnotations.initMocks(this);
-        inAppManager = spy(new IterableInAppManager(iterableApiMock, handlerMock, null, 30.0, storageMock, activityMonitorMock, inAppDisplayerMock));
+        inAppManager = spy(new IterableInAppManager(iterableApiMock, handlerMock, 30.0, storageMock, activityMonitorMock, inAppDisplayerMock));
         doAnswer(new Answer() {
             @Override
             public Object answer(InvocationOnMock invocation) throws Throwable {