The methods below require the OneSignal SDK versions 3 & 4.

It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.

See Update to User Model for migration steps.

In-App Triggers

Triggers are events that you fire to show In-App Messages within your app. 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.

`addTrigger` Method

Add a trigger. May show an In-App Message if its trigger conditions were met.

Parameter	Type	Description
`key`	String, NSString	Key for the trigger.
`value`	Object, id(String or number recommended)	Value for the trigger. Object passed in will be converted to a string.

OneSignal.addTrigger("level", 5);

`addTriggers` Method

Add a map of triggers. May show an In-App Message if its trigger conditions were met.

Parameter	Type	Description
`triggers`	Map<String, Object>, NSDictionary<NSString *, id>	Allows you to set multiple trigger key/value pairs simultaneously.

HashMap<String, Object> testTriggers = new HashMap<>();
testTriggers.put("test1", "value1");
testTriggers.put("test2", "value2");

OneSignal.addTriggers(testTriggers);

`removeTriggerForKey` Method

Removes a single trigger for the given key. May show an In-App Message if its trigger conditions were met.

Parameter	Type	Description
`key`	String, NSString	Key for trigger to remove.

OneSignal.removeTriggerForKey("level");

`removeTriggersForKeys` Method

Removes a list of triggers based on a collection of keys. May show an In-App Message if its trigger conditions were met.

OneSignal.Default.RemoveTriggers(new[] { "trigger4", "trigger5" });

Parameter	Type	Description
`keys`	Collection	Removes a collection of triggers from their keys.

`getTriggerValueForKey` Method

Gets a trigger value for a provided trigger key.

Parameter	Type	Description
`key`	String, NSString	Returns a single trigger value for the given key, if it exists, otherwise returns `null` or `nil` in iOS.

Return Type	Description
Object (Android) id (iOS) String (Unity)	Value if added with `addTrigger`, or `null`/`nil` (iOS) if never set.

Object triggerValue;
triggerValue = OneSignal.getTriggerValueForKey("level");

Prevent In-App From Showing Temporarily

`pauseInAppMessages` Method

Allows you to temporarily pause all In-App Messages. You may want to do this while the user is engaged in an activity that you don’t want a message to interrupt (such as watching a video).

OneSignal.Default.InAppMessagesArePaused = true;

Parameter	Type	Description
`pause`	Boolean	To pause, set `true`. To resume, set `false`.

In-App Message Click Handler

`setInAppMessageClickHandler` Method

Sets an In-App Message opened handler. The instance will be called when an In-App Message action is tapped on.

Parameter	Type	Description
`handler`	`OSInAppMessageClickHandler` (Android)`OSInAppMessageClickBlock` (iOS)	Instance to a class implementing this interference.

In-App Message Click HandlerUse to process an In-App Message the user just tapped on.

Parameter	Type	Description
`result`	`OSInAppMessageAction`	Details about the In-App Message action element (button or image) that was tapped on.

OneSignal.setInAppMessageClickHandler(new OneSignal.OSInAppMessageClickHandler() {
    @Override
    public void inAppMessageClicked(OSInAppMessageAction result) {
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "getClickUrl: " + result.getClickUrl());
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "getClickName: " + result.getClickName());
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "getUrlTarget: " + String.valueOf(result.getUrlTarget()));
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "getOutcomes: " + String.valueOf(result.getOutcomes()));
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "getPrompts: " + String.valueOf(result.getPrompts()));
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "doesCloseMessage: " + String.valueOf(result.doesCloseMessage()));
    }
});

`OSInAppMessageAction` Class

Details about the In-App Message action element (button or image) that was tapped on.

Type	Method/Property	Description
String``NSString	getClickName()``clickName``click_name	An optional click name defined for the action element.`null` or `nil` (iOS) if not set
String``NSURL	getClickUrl()``clickUrl``click_url	An optional URL that opens when the action takes place.`null` or `nil` (iOS) if not set.
boolean``BOOL	isFirstClick()``firstClick``first_click	`true` if this is the first time the user has pressed any action on the In-App Message.
boolean``BOOL	doesCloseMessage()``closesMessage``closes_message	`true` = the In-App Message will animate off the screen. `false` = the In-App Message will stay on screen until the user dismisses it.
List<OSInAppMessageOutcome>``NSArray<OSInAppMessageOutcome *>	getOutcomes()``outcomes	Outcome for action. Mainly useful for debugging
List<OSInAppMessagePrompt>``OSInAppMessagePrompt	getPrompts()``prompts	Permission prompts. Mainly useful for debugging
`OSInAppMessageTag`	getTags()``tags	Tags for action. Mainly useful for debugging
`OSInAppMessageActionUrlType`	getUrlTarget()``urlTarget``url_target	Determines where the URL is opened, ie. Mainly useful for debugging

In-App Message Lifecycle Handler

Requires iOS SDK version 3.7.0+ Requires Android SDK version 4.6.0+

The In-App Message Lifecycle Handler gives insight into the display lifecycle of In-App Messages. The Lifecycle Handler has four lifecycle methods that you can override in order to run code at particular times in this process.

`setInAppMessageLifecycleHandler` Method

Sets an In-App Message lifecycle handler.

Parameter	Type	Description
`handler` (Android)`delegate` (iOS)	`OSInAppMessageLifecycleHandler`	Instance of a class implementing this abstract class/protocol.

The OSInAppMessageLifecycleHandler Class/Protocol includes the following optional methods.

Method	Details
`onWillDisplayInAppMessage(OSInAppMessage message)`	This method will be called after the In-App Message content has been loaded, but before it has been displayed. If the content load fails, this method will not be called.
`onDidDisplayInAppMessage(OSInAppMessage message)`	This method will be called after the In-App Message is displayed on screen.
`onWillDismissInAppMessage(OSInAppMessage message)`	This method will be called when an an event to dismiss the In-App Message is fired. This method is also called for auto-dismissed In-App Messages.
`onDidDismissInAppMessage(OSInAppMessage message)`	This method will be called when the In-App Message is completely dismissed from the screen.

OneSignal.setInAppMessageLifecycleHandler(
    new OSInAppMessageLifecycleHandler() {

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

        @Override
        public void onWillDisplayInAppMessage(OSInAppMessage message) {
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "OSInAppMessageLifecycleHandler: onWillDisplay Message: " + message.getMessageId());
        }

        @Override
        public void onDidDisplayInAppMessage(OSInAppMessage message) {
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "OSInAppMessageLifecycleHandler: onDidDisplay Message: " + message.getMessageId();
        }

        @Override   
        public void onWillDismissInAppMessage(OSInAppMessage message) { 
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "OSInAppMessageLifecycleHandler: onWillDismiss Message: " + message.getMessageId());
        }
    
        @Override
        public void onDidDismissInAppMessage(OSInAppMessage message) {
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "OSInAppMessageLifecycleHandler: onDidDismiss Message: " + message.getMessageId());
        }    
});

`OSInAppMessage` ClassIdentifiable details of an In-App Message.

Type	Method/Property	Description
String``NSString	getMessageId()``messageId	The generated ID of the In-App Message.

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

v3-4 SDK In-App Message SDK Methods

In-App Triggers

`addTrigger` Method

`addTriggers` Method

`removeTriggerForKey` Method

`removeTriggersForKeys` Method

`getTriggerValueForKey` Method

Prevent In-App From Showing Temporarily

`pauseInAppMessages` Method

In-App Message Click Handler

`setInAppMessageClickHandler` Method

In-App Message Click HandlerUse to process an In-App Message the user just tapped on.

`OSInAppMessageAction` Class

In-App Message Lifecycle Handler

`setInAppMessageLifecycleHandler` Method

`OSInAppMessage` ClassIdentifiable details of an In-App Message.

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

​In-App Triggers

​addTrigger Method

​addTriggers Method

​removeTriggerForKey Method

​removeTriggersForKeys Method

​getTriggerValueForKey Method

​Prevent In-App From Showing Temporarily

​pauseInAppMessages Method

​In-App Message Click Handler

​setInAppMessageClickHandler Method

​In-App Message Click HandlerUse to process an In-App Message the user just tapped on.

​OSInAppMessageAction Class

​In-App Message Lifecycle Handler

​setInAppMessageLifecycleHandler Method

​OSInAppMessage ClassIdentifiable details of an In-App Message.

In-App Triggers

`addTrigger` Method

`addTriggers` Method

`removeTriggerForKey` Method

`removeTriggersForKeys` Method

`getTriggerValueForKey` Method

Prevent In-App From Showing Temporarily

`pauseInAppMessages` Method

In-App Message Click Handler

`setInAppMessageClickHandler` Method

In-App Message Click HandlerUse to process an In-App Message the user just tapped on.

`OSInAppMessageAction` Class

In-App Message Lifecycle Handler

`setInAppMessageLifecycleHandler` Method

`OSInAppMessage` ClassIdentifiable details of an In-App Message.