> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v3-4 SDK In-App Message SDK Methods

> OneSignal Mobile SDK Methods for In-App Messages

<Warning>
  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](/docs/en/user-model-migration-guide) for migration steps.
</Warning>

# 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. |

<CodeGroup>
  ```java java theme={null}
  OneSignal.addTrigger("level", 5);
  ```

  ```swift Swift theme={null}
  OneSignal.addTrigger("prompt_ios", withValue: "true");
  ```

  ```objectivec objectivec theme={null}
  [OneSignal addTrigger:@"product" withVaue:@"aggieTee"]
  ```

  ```csharp Unity (C#) theme={null}
  OneSignal.Default.SetTrigger("triggerKey", 123);
  ```

  ```javascript React Native theme={null}
  OneSignal.addTrigger("level", 5);
  ```

  ```javascript Flutter theme={null}
  OneSignal.shared.addTrigger("level", 5);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
  window.plugins.OneSignal.addTrigger("level", 5);
  ```

  ```csharp Xamarin theme={null}
  OneSignal.Current.AddTrigger("trigger_1", "one");
  ```

  ```lua Corona theme={null}
  --Currently IAM not available for Corona
  ```

  ```javascript Web-JavaScript theme={null}
  //Currently IAM not available for Web, let us know your interested!
  ```
</CodeGroup>

## `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. |

<CodeGroup>
  ```java java theme={null}
  HashMap<String, Object> testTriggers = new HashMap<>();
  testTriggers.put("test1", "value1");
  testTriggers.put("test2", "value2");

  OneSignal.addTriggers(testTriggers);
  ```

  ```swift Swift theme={null}
  OneSignal.addTriggers(["checkoutStep":"3", "product":"aggieHat"])
  ```

  ```objectivec objectivec theme={null}
  NSDictionary *triggers = @{
  	@"checkoutStep": @"3",
  	@"product": @"aggieHat"
  };

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

  [OneSignal addTriggers:triggers]
  ```

  ```csharp Unity (C#) theme={null}
  OneSignal.Default.SetTriggers(new Dictionary<string, object> {
      ["trigger1"] = "abc",
      ["trigger2"] = 456
  });
  ```

  ```javascript React Native theme={null}
  OneSignal.addTriggers({"isLonghorn":"true", "clicked":"true"});
  ```

  ```javascript Flutter theme={null}
  Map<String, Object> triggers = new Map<String, Object>();
  triggers["trigger_2"] = "two";
  triggers["trigger_3"] = "three";
  OneSignal.shared.addTriggers(triggers);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
  window.plugins.OneSignal.addTriggers({"isAggie":"true", "clicked":"true"});
  ```

  ```csharp Xamarin theme={null}
  Dictionary<string, object> triggers = new Dictionary<string, object>();
  triggers.Add("trigger_2", "two");
  triggers.Add("trigger_3", "three");
  OneSignal.Current.AddTriggers(triggers);
  ```

  ```lua Corona theme={null}
  --Currently IAM not available for Corona
  ```

  ```javascript Web-JavaScript theme={null}
  //Currently IAM not available for Web, let us know your interested!
  ```
</CodeGroup>

## `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. |

<CodeGroup>
  ```java java theme={null}
  OneSignal.removeTriggerForKey("level");
  ```

  ```swift Swift theme={null}
  OneSignal.removeTriggerForKey("product");
  ```

  ```objectivec objectivec theme={null}
  [OneSignal removeTriggerForKey:@"product"]
  ```

  ```csharp Unity (C#) theme={null}
  OneSignal.Default.RemoveTrigger("trigger3");
  ```

  ```javascript React Native theme={null}
  OneSignal.removeTriggerForKey("isLonghorn");
  ```

  ```javascript Flutter theme={null}
  OneSignal.shared.removeTriggerForKey("isAggie");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
  window.plugins.OneSignal.removeTriggerForKey("isAggie");
  ```

  ```csharp Xamarin theme={null}
  OneSignal.Current.RemoveTriggerForKey("trigger_2");
  ```

  ```lua Corona theme={null}
  --Currently IAM not available for Corona
  ```

  ```javascript Web-JavaScript theme={null}
  //Currently IAM not available for Web, let us know your interested!
  ```
</CodeGroup>

## `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.

<CodeGroup>
  ```csharp Unity(C#) theme={null}
  OneSignal.Default.RemoveTriggers(new[] { "trigger4", "trigger5" });
  ```
</CodeGroup>

| 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. |

<CodeGroup>
  ```java java theme={null}
  Object triggerValue;
  triggerValue = OneSignal.getTriggerValueForKey("level");
  ```

  ```swift Swift theme={null}
  OneSignal.getTriggerValueForKey("product");
  ```

  ```objectivec objectivec theme={null}
  [OneSignal getTriggerValueForKey:@"product"]
  ```

  ```csharp Unity (C#) theme={null}
  // Get the current value to a trigger by key
  var triggerValue = OneSignal.Default.GetTrigger("key");
  ```

  ```javascript React Native theme={null}
  OneSignal.getTriggerValueForKey("isLonghorn", function (value) {
    console.log("isLonghorn:", value)
  });
  ```

  ```javascript Flutter theme={null}
  Object triggerValue = await OneSignal.shared.getTriggerValueForKey("myTrigger");
  print("myTrigger key trigger value: " + triggerValue);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
  window.plugins.OneSignal.getTriggerValueForKey("isAggie", function (value) {
    console.log("isAggie:", value)
  });
  ```

  ```csharp Xamarin theme={null}
  object value = OneSignal.Current.GetTriggerValueForKey("trigger_1");
  Debug.WriteLine("trigger_1 value: " + value);
  ```

  ```lua Corona theme={null}
  --Currently IAM not available for Corona
  ```

  ```javascript Web-JavaScript theme={null}
  //Currently IAM not available for Web, let us know your interested!
  ```
</CodeGroup>

# 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).

<CodeGroup>
  ```csharp Unity(C#) theme={null}
  OneSignal.Default.InAppMessagesArePaused = true;
  ```
</CodeGroup>

| 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. |

<CodeGroup>
  ```java java theme={null}
  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()));
      }
  });
  ```

  ```swift Swift theme={null}
  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)
  ```

  ```objectivec objectivec theme={null}
  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]
  ```

  ```csharp Unity (C#) theme={null}
  OneSignal.Default.InAppMessageTriggeredAction += onIAMTriggedAction;

  void onIAMTriggedAction(InAppMessageAction action) {
      var clickName  = action.clickName;
      var firstClick = action.firstClick;
  }
  ```

  ```javascript React Native theme={null}
  OneSignal.setInAppMessageClickHandler(event => {
  	console.log("OneSignal IAM clicked:", event);
  });
  ```

  ```javascript Flutter theme={null}
  OneSignal.shared.setInAppMessageClickedHandler((OSInAppMessageAction action) {
       print('OneSignal: IAM clicked action: ${action}');
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  // 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;
  });
  ```

  ```csharp Xamarin theme={null}
  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();
  ```
</CodeGroup>

## `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.                                                                               |

<CodeGroup>
  ```java java theme={null}
  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());
          }    
  });
  ```

  ```objectivec objectivec theme={null}
  // 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);
  }
  ```

  ```swift Swift theme={null}
  // 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)")
      }
  }
  ```

  ```csharp Unity (C#) theme={null}
  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)}");
  }
  ```
</CodeGroup>

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

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

***