In-App Message SDK Methods

OneSignal Mobile SDK Methods for In-App Messages

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);
OneSignal.addTrigger("prompt_ios", withValue: "true");
[OneSignal addTrigger:@"product" withVaue:@"aggieTee"]
OneSignal.Default.SetTrigger("triggerKey", 123);
OneSignal.addTrigger("level", 5);
OneSignal.shared.addTrigger("level", 5);
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.addTrigger("level", 5);
OneSignal.Current.AddTrigger("trigger_1", "one");
--Currently IAM not available for Corona
//Currently IAM not available for Web, let us know your interested!

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);
OneSignal.addTriggers(["checkoutStep":"3", "product":"aggieHat"])
NSDictionary *triggers = @{
    @"checkoutStep": @"3",
    @"product": @"aggieHat"
};

[OneSignal addTriggers:triggers]
NSDictionary *triggers = @{
    @"checkoutStep": @"3",
    @"product": @"aggieHat"
};

[OneSignal addTriggers:triggers]
OneSignal.Default.SetTriggers(new Dictionary<string, object> {
    ["trigger1"] = "abc",
    ["trigger2"] = 456
});
OneSignal.addTriggers({"isLonghorn":"true", "clicked":"true"});
Map<String, Object> triggers = new Map<String, Object>();
triggers["trigger_2"] = "two";
triggers["trigger_3"] = "three";
OneSignal.shared.addTriggers(triggers);
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.addTriggers({"isAggie":"true", "clicked":"true"});
Dictionary<string, object> triggers = new Dictionary<string, object>();
triggers.Add("trigger_2", "two");
triggers.Add("trigger_3", "three");
OneSignal.Current.AddTriggers(triggers);
--Currently IAM not available for Corona
//Currently IAM not available for Web, let us know your interested!

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");
OneSignal.removeTriggerForKey("product");
[OneSignal removeTriggerForKey:@"product"]
OneSignal.Default.RemoveTrigger("trigger3");
OneSignal.removeTriggerForKey("isLonghorn");
OneSignal.shared.removeTriggerForKey("isAggie");
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.removeTriggerForKey("isAggie");
OneSignal.Current.RemoveTriggerForKey("trigger_2");
--Currently IAM not available for Corona
//Currently IAM not available for Web, let us know your interested!

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");
OneSignal.getTriggerValueForKey("product");
[OneSignal getTriggerValueForKey:@"product"]
// Get the current value to a trigger by key
var triggerValue = OneSignal.Default.GetTrigger("key");
OneSignal.getTriggerValueForKey("isLonghorn", function (value) {
  console.log("isLonghorn:", value)
});
Object triggerValue = await OneSignal.shared.getTriggerValueForKey("myTrigger");
print("myTrigger key trigger value: " + triggerValue);
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.getTriggerValueForKey("isAggie", function (value) {
  console.log("isAggie:", value)
});
object value = OneSignal.Current.GetTriggerValueForKey("trigger_1");
Debug.WriteLine("trigger_1 value: " + value);
--Currently IAM not available for Corona
//Currently IAM not available for Web, let us know your interested!

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 Handler

Use 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()));
    }
});
let inAppMessageClickBlock: OSInAppMessageClickBlock = { action in
    if let clickName = action.clickName {
        print("clickName string: ", clickName)
    }
    if let clickUrl = action.clickUrl {
        print ("clickUrl string: ", clickUrl)
    }
    if let firstClick = action.firstClick {
        print("firstClick bool: ", firstClick)
    }
    if let closesMessage = action.closesMessage {
        print("closesMessage bool: ", closesMessage)
    }
}

OneSignal.setInAppMessageClickHandler(inAppMessageClickBlock)
id inAppMessageClickBlock = ^(OSInAppMessageAction *action) {
        NSString *message = [NSString stringWithFormat:@"Click Action Occurred: clickName:%@ clickUrl:%@ firstClick:%i closesMessage:%i",
                             action.clickName,
                             action.clickUrl,
                             action.firstClick,
                             action.closesMessage];
        [OneSignal onesignal_Log:ONE_S_LL_DEBUG message:message];
    };

[OneSignal setInAppMessageClickHandler:inAppMessageClickBlock]
OneSignal.Default.InAppMessageTriggeredAction += onIAMTriggedAction;

void onIAMTriggedAction(InAppMessageAction action) {
    var clickName  = action.clickName;
    var firstClick = action.firstClick;
}
OneSignal.setInAppMessageClickHandler(event => {
    console.log("OneSignal IAM clicked:", event);
});
OneSignal.shared.setInAppMessageClickedHandler((OSInAppMessageAction action) {
     print('OneSignal: IAM clicked action: ${action}');
});
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.setInAppMessageClickHandler(function(result){
    let firstClick = result.first_click;
    let closesMessage = result.closes_message;
    let clickUrl = result.click_url;
    let clickName = result.click_name;
});
OneSignal.Current.StartInit("b0f7f966-d8ec-11e4-bed1-df8f05je55ba").Settings(new Dictionary<string, bool>() {
            { IOSSettings.kOSSettingsKeyAutoPrompt, false },
            { IOSSettings.kOSSettingsKeyInAppLaunchURL, true } })
           .HandleInAppMessageClicked((action) =>
           {
              // Example IAM click handling for IAM elements
              Debug.WriteLine("HandledInAppMessageClicked: {0}", action.clickName);
           })
           .EndInit();

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());
        }    
});
// AppDelegate.h
// Add OSInAppMessageLifecycleHandler as an implemented protocol of the class that will handle the In-App Message lifecycle events.
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSInAppMessageLifecycleHandler>
@end

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

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

- (void)onWillDisplayInAppMessage:(OSInAppMessage *)message {
    NSLog(@"OSInAppMessageLifecycleHandler: onWillDisplay Message: %@", message.messageId);
}

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

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

- (void)onDidDismissInAppMessage:(OSInAppMessage *)message {
    NSLog(@"OSInAppMessageLifecycleHandler: onDidDismiss Message: %@", message.messageId);
}
// AppDelegate.swift
// Add OSInAppMessageLifecycleHandler as an implemented protocol of the class that will handle the In-App Message lifecycle events.
class AppDelegate: UIResponder, UIApplicationDelegate, OSInAppMessageLifecycleHandler {

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

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

    func onWillDisplay(_ message: OSInAppMessage!) {
        print("OSInAppMessageLifecycleHandler: onDidDisplay Message: \(message.messageId)")
    }
}
OneSignal.Default.InAppMessageWillDisplay     += _iamWillDisplay;
OneSignal.Default.InAppMessageDidDisplay      += _iamDidDisplay;
OneSignal.Default.InAppMessageWillDismiss     += _iamWillDismiss;
OneSignal.Default.InAppMessageDidDismiss      += _iamDidDismiss;

void _iamWillDisplay(InAppMessage inAppMessage) {
    Debug.Log($"IAM will display: {JsonUtility.ToJson(inAppMessage)}");
}

void _iamDidDisplay(InAppMessage inAppMessage) {
    Debug.Log($"IAM did display: {JsonUtility.ToJson(inAppMessage)}");
}

void _iamWillDismiss(InAppMessage inAppMessage) {
    Debug.Log($"IAM will dismiss: {JsonUtility.ToJson(inAppMessage)}");
}

void _iamDidDismiss(InAppMessage inAppMessage) {
    Debug.Log($"IAM did dismiss: {JsonUtility.ToJson(inAppMessage)}");
}

OSInAppMessage Class

Identifiable details of an In-App Message.

Type

Method/Property

Description

String
NSString

getMessageId()
messageId

The generated ID of the In-App Message.


Did this page help you?