In-App Message SDK Methods

OneSignal Mobile SDK Methods for In-App Messages

Trigger Methods

Triggers are used to determine whether a specific IAM should be presented to the user. See Triggers.
They are created within the OneSignal Dashboard.

Every time you add or remove a trigger with the below methods, the OneSignal SDK will evaluate if an In-App Message should be shown based on the conditions set on it when it was created in the OneSignal Dashboard.

Triggers are reset each time your app is closed, so make sure to set them again when starting your app if you need any of them to be persistent.

Adding a trigger

Add a trigger for the current user. If the trigger key already exists, it will be replaced with the value provided.

OneSignal.getInAppMessages().addTrigger("KEY", "VALUE");

OneSignal.InAppMessages.addTrigger("KEY", "VALUE")

[OneSignal.InAppMessages addTrigger:@"KEY" withValue:@"VALUE"];

OneSignal.InAppMessages.addTrigger("KEY", "VALUE")

OneSignal.InAppMessages.AddTrigger("KEY", "VALUE");
OneSignal.InAppMessages.addTrigger("triggerKey", "triggerValue");
OneSignal.InAppMessages.addTrigger("trigger_1", "one");
window.plugins.OneSignal.InAppMessages.addTrigger("triggerKey", "triggerValue");

📘

Triggers are not persisted

Note that triggers are not persisted to the backend. They only exist on the local device and apply to the current user.

Adding several triggers at once

Add multiple triggers for the current user. If any trigger key already exists, it will be replaced with the value provided here.

OneSignal.getInAppMessages()
  .addTriggers(new HashMap<String, String>() {{
    put("KEY_01","VALUE_01");
    put("KEY_02", "VALUE_02");
  }});

OneSignal.InAppMessages.addTriggers(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))

[OneSignal.InAppMessages addTriggers:@{@"KEY_01": @"VALUE_01", @"KEY_02": @"VALUE_02"}];

OneSignal.InAppMessages.addTriggers(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"])

OneSignal.InAppMessages.AddTriggers(new Dictionary<string, string> {
  { "KEY_01", "VALUE_01" },
  { "KEY_02", "VALUE_02" }
});
OneSignal.InAppMessages.addTriggers({"triggerKey1":"triggerValue", "triggerKey2":"triggerValue"});
Map<String, String> triggers = new Map<String, String>();
triggers["trigger_2"] = "two";
triggers["trigger_3"] = "three";
OneSignal.InAppMessages.addTriggers(triggers);
window.plugins.OneSignal.InAppMessages.addTriggers({"triggerKey1":"triggerValue", "triggerKey2":"triggerValue"});

Removing a trigger

Remove the trigger with the provided key from the current user.

OneSignal.getInAppMessages().removeTrigger("KEY");

OneSignal.InAppMessages.removeTrigger("KEY")

[OneSignal.InAppMessages removeTrigger:@"KEY"];

OneSignal.InAppMessages.removeTrigger("KEY")

OneSignal.InAppMessages.RemoveTrigger("KEY");
OneSignal.InAppMessages.removeTrigger("triggerKey");
OneSignal.InAppMessages.removeTrigger("trigger_1");
window.plugins.OneSignal.InAppMessages.removeTrigger("triggerKey");

Removing multiple triggers at once

Remove multiple triggers from the current user.

OneSignal.getInAppMessages().removeTriggers(Arrays.asList("KEY_01", "KEY_02"));
OneSignal.InAppMessages.removeTriggers(setOf("KEY_01", "KEY_02")

[OneSignal.InAppMessages removeTriggers:@[@"KEY_01", @"KEY_02"]];

OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"])

OneSignal.InAppMessages.RemoveTriggers(new string[] { "KEY_01", "KEY_2" });
OneSignal.InAppMessages.removeTriggers(["triggerKey1", "triggerKey2"]);
List<String> triggerKeys = ["trigger_1", "trigger_3"];
OneSignal.InAppMessages.removeTriggers(triggerKeys);
window.plugins.OneSignal.InAppMessages.removeTriggers(["triggerKey1", "triggerKey2"]);

Removing all triggers

Clear all triggers from the current user.

OneSignal.getInAppMessages().clearTriggers();

OneSignal.InAppMessages.clearTriggers()

[OneSignal.InAppMessages clearTriggers];

OneSignal.InAppMessages.clearTriggers()

OneSignal.InAppMessages.ClearTriggers();
OneSignal.InAppMessages.clearTriggers();
OneSignal.InAppMessages.clearTriggers();
window.plugins.OneSignal.InAppMessages.clearTriggers();

In-App Message Lifecycle

Pausing all In-App messages

Set whether in-app messaging is currently paused. When set to true, no In-App messages will be presented to the user regardless of whether they qualify for them. When set to false, any messages the user qualifies for will be presented to them at the appropriate time.

OneSignal.getInAppMessages().setPaused(true);
OneSignal.InAppMessages.paused = true
[OneSignal.InAppMessages paused:true];

// Get `paused` state
BOOL paused = [OneSignal.InAppMessages paused];
OneSignal.InAppMessages.paused = true

// Get `paused` state
let paused = OneSignal.InAppMessages.paused
OneSignal.InAppMessages.Paused = true;
OneSignal.InAppMessages.setPaused(true);
OneSignal.InAppMessages.paused(true);
window.plugins.OneSignal.InAppMessages.setPaused(true);

Respond to In-App Message display

Use the InAppMessageLifecycleListener methods to respond to In App Messages being displayed and dismissed.

OneSignal.getInAppMessages().addLifecycleListener(new IInAppMessageLifecycleListener() {
    @Override
    public void onWillDisplay(@NonNull IInAppMessageWillDisplayEvent event) {
        Log.v(Tag.LOG_TAG, "onWillDisplayInAppMessage");
    }

    @Override
    public void onDidDisplay(@NonNull IInAppMessageDidDisplayEvent event) {
        Log.v(Tag.LOG_TAG, "onDidDisplayInAppMessage");
    }

    @Override
    public void onWillDismiss(@NonNull IInAppMessageWillDismissEvent event) {
        Log.v(Tag.LOG_TAG, "onWillDismissInAppMessage");
    }

    @Override
    public void onDidDismiss(@NonNull IInAppMessageDidDismissEvent event) {
        Log.v(Tag.LOG_TAG, "onDidDismissInAppMessage");
    }
});

val lifecycleListener = object : IInAppMessageLifecycleListener {
    override fun onWillDisplay(event: IInAppMessageWillDisplayEvent) {
        print(event.message.messageId)
    }

    override fun onDidDisplay(event: IInAppMessageDidDisplayEvent) {
        print(event.message.messageId)
    }

    override fun onWillDismiss(event: IInAppMessageWillDismissEvent) {
        print(event.message.messageId)
    }

    override fun onDidDismiss(event: IInAppMessageDidDismissEvent) {
        print(event.message.messageId)
    }
}
OneSignal.InAppMessages.addLifecycleListener(lifecycleListener)
OneSignal.InAppMessages.removeLifecycleListener(lifecycleListener)

// AppDelegate.h
// Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSInAppMessageLifecycleListener>
@end

// AppDelegate.m
@implementation AppDelegate
  
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Add your implementing class as the listener.  
    [OneSignal.InAppMessages addLifecycleListener:self];
}

// Add one or more of the following optional lifecycle methods
- (void)onWillDisplayInAppMessage:(OSInAppMessageWillDisplayEvent *)event {
  NSLog(@"OSInAppMessageLifecycleListener: onWillDisplay Message: %@", event.message.messageId);
}

- (void)onDidDisplayInAppMessage:(OSInAppMessageDidDisplayEvent *)event {
  NSLog(@"OSInAppMessageLifecycleListener: onDidDisplay Message: %@", event.message.messageId);
}

- (void)onWillDismissInAppMessage:(OSInAppMessageWillDismissEvent *)event {
  NSLog(@"OSInAppMessageLifecycleListener: onWillDismiss Message: %@", event.message.messageId);
}

- (void)onDidDismissInAppMessage:(OSInAppMessageDidDismissEvent *)event {
  NSLog(@"OSInAppMessageLifecycleListener: onDidDismiss Message: %@", event.message.messageId);
}

// AppDelegate.swift
// Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.
class AppDelegate: UIResponder, UIApplicationDelegate, OSInAppMessageLifecycleListener {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Add your implementing class as the listener
    OneSignal.InAppMessages.addLifecycleListener(self)
  }

  // Add one or more of the following optional lifecycle methods

  func onWillDisplay(event: OSInAppMessageWillDisplayEvent) {
    print("OSInAppMessageLifecycleListener: onWillDisplay Message: \(event.message.messageId)")
  }
  func onDidDisplay(event: OSInAppMessageDidDisplayEvent) {
    print("OSInAppMessageLifecycleListener: onDidDisplay Message: \(event.message.messageId)")
  }
  func onWillDismiss(event: OSInAppMessageWillDismissEvent) {
    print("OSInAppMessageLifecycleListener: onWillDismiss Message: \(event.message.messageId)")
  }
  func onDidDisplay(event: OSInAppMessageDidDisplayEvent) {
    print("OSInAppMessageLifecycleListener: onDidDismiss Message: \(event.message.messageId)")
	}
}

OneSignal.InAppMessages.WillDisplay += (sender, e) =>
  {
    // Access the in-app message with e.Message
  };

OneSignal.InAppMessages.DidDisplay += (sender, e) =>
  {
    // Access the in-app message with e.Message
  };

OneSignal.InAppMessages.WillDismiss += (sender, e) =>
  {
    // Access the in-app message with e.Message
  };

OneSignal.InAppMessages.DidDismiss += (sender, e) =>
  {
    // Access the in-app message with e.Message
  };
OneSignal.InAppMessages.addEventListener('willDisplay', (event) => {
  console.log('OneSignal: will display IAM: ', event);
});

OneSignal.InAppMessages.addEventListener('didDisplay', (event) => {
  console.log('OneSignal: did display IAM: ', event);
});

OneSignal.InAppMessages.addEventListener('willDismiss', (event) => {
  console.log('OneSignal: will dismiss IAM: ', event);
});

OneSignal.InAppMessages.addEventListener('didDismiss', (event) => {
  console.log('OneSignal: did dismiss IAM: ', event);
});
OneSignal.InAppMessages.addWillDisplayListener((event) {
	print("ON WILL DISPLAY IN APP MESSAGE ${event.message.messageId}");
});
OneSignal.InAppMessages.addDidDisplayListener((event) {
	print("ON DID DISPLAY IN APP MESSAGE ${event.message.messageId}");
});
OneSignal.InAppMessages.addWillDismissListener((event) {
	print("ON WILL DISMISS IN APP MESSAGE ${event.message.messageId}");
});
OneSignal.InAppMessages.addDidDismissListener((event) {
	print("ON DID DISMISS IN APP MESSAGE ${event.message.messageId}");
});
// Define the lifecycle listener functions
let willDisplayListener = async function(event) {
  console.log("OneSignal: will display IAM: "+ event.messageId);
};
let didDisplayListener = async function(event) {
  console.log("OneSignal: did display IAM: "+ event.messageId);
};
let willDismissListener = async function(event) {
  console.log("OneSignal: will dismiss IAM: "+ event.messageId);
};
let didDismissListener = async function(event) {
  console.log("OneSignal: did dismiss IAM: "+ event.messageId);
};

// Listeners for each event added separately
window.plugins.OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);
window.plugins.OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);
window.plugins.OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);
window.plugins.OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);

Respond to In-App Click Events

To respond to In App Message click events add a click listener. The event contains the message that was clicked as well as a result object for the click that provides the

  • actionId: String - The action id set for the In-App Message element that was clicked
  • urlTarget: Enumeration - Specifies where the launch url for the In-App Message will be presented
  • url: String - The launch url for the action if any
  • closingMessage: Boolean - Indicates if the action results in the In-App Message being closed
OneSignal.getInAppMessages().addClickListener(new IInAppMessageClickListener() {
    @Override
    public void onClick(@Nullable IInAppMessageClickEvent event) {
        Log.v(Tag.LOG_TAG, "INotificationClickListener.inAppMessageClicked");
    }
});
val clickListener = object : IInAppMessageClickListener {
    override fun onClick(event: IInAppMessageClickEvent) {
        print(event.result.actionId)
    }
}
OneSignal.InAppMessages.addClickListener(clickListener)

// Add this method to object implementing the OSInAppMessageClickListener protocol
- (void)onClickInAppMessage:(OSInAppMessageClickEvent * _Nonnull)event {
    NSLog(@"onClickInAppMessage event: %@", [event jsonRepresentation]);
    NSString *message = [NSString stringWithFormat:@"In App Message Click Occurred: messageId: %@ actionId: %@ url: %@ urlTarget: %@ closingMessage: %i",
                        event.message.messageId,
                        event.result.actionId,
                        event.result.url,
                        @(event.result.urlTarget),
                        event.result.closingMessage];
}

// Add your object as a listener
[OneSignal.InAppMessages addClickListener:self];

class MyInAppMessageClickListener : NSObject, OSInAppMessageClickListener {
    func onClick(event: OSInAppMessageClickEvent) {
        let messageId = event.message.messageId
        let result: OSInAppMessageClickResult = event.result
        let actionId = result.actionId
        let url = result.url
        let urlTarget: OSInAppMessageActionUrlType = result.urlTarget
        let closingMessage = result.closingMessage
    }
}

// Add your object as a listener
let myListener = MyInAppMessageClickListener()
OneSignal.InAppMessages.addClickListener(myListener)

OneSignal.InAppMessages.Clicked += (sender, e) =>
  {
    // Access the in-app message with e.Message and the click result with e.Result
  };
OneSignal.InAppMessages.addEventListener('click', (event) => {
  console.log('OneSignal IAM clicked:', event);
});
OneSignal.InAppMessages.addClickListener((event) {
	print("In App Message Clicked: \n${event.result.jsonRepresentation().replaceAll("\\n", "\n")}");
});
let inAppClickListener = async function(event) {
  let clickData = JSON.stringify(event);
  console.log("In-App Message Clicked: "+ clickData);
};
window.plugins.OneSignal.InAppMessages.addEventListener("click", inAppClickListener);