iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIUserNotificationAction Class Reference

Options
Deployment Target:

On This Page
Language:

UIUserNotificationAction

A UIUserNotificationAction object represents a custom action that your app can perform in response to a remote or local notification. When a notification is delivered, the system displays a button for each custom action associated with the notification. Tapping a button launches your app (either in the foreground or background) and gives you a chance to perform the indicated action. You use this class to specify the text that is displayed in the button and the information your app needs to perform the corresponding action.

Typically, you create an instance of the UIMutableUserNotificationAction class instead of this class. You use the mutable object to configure the action and then call the setActions:forContext: method of UIMutableUserNotificationActionSettings to add the resulting actions to a group.

For each action you define, you must specify whether execution of that action requires the app to be running in the foreground or background. You can also specify whether the device must be unlocked or can remain locked while the action is performed. Unlocking the device may be necessary if the action involves reading or writing files that are encrypted on disk using the system’s data protection mechanism. When the user selects an action, the system puts your app into the appropriate mode and calls your app delegate’s application:handleActionWithIdentifier:forRemoteNotification:completionHandler: or application:handleActionWithIdentifier:forLocalNotification:completionHandler: method to perform the action.

  • The mode in which to run the app when the action is performed. (read-only)

    Declaration

    Swift

    var activationMode: UIUserNotificationActivationMode { get }

    Objective-C

    @property(nonatomic, assign, readonly) UIUserNotificationActivationMode activationMode

    Discussion

    If the value in this property is UIUserNotificationActivationModeForeground, the value of the authenticationRequired property is assumed to be YEStrue regardless of its actual value.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the user must unlock the device before the action is performed. (read-only)

    Declaration

    Swift

    var authenticationRequired: Bool { get }

    Objective-C

    @property(nonatomic, assign, readonly, getter=isAuthenticationRequired) BOOL authenticationRequired

    Discussion

    The value of this property is ignored and treated as a value of YEStrue when the value of the activationMode property is set to UIUserNotificationActivationModeForeground.

    If your app uses data protection to encrypt data on disk, consider the data needs of the corresponding action before setting this property to NOfalse. For many data protection classes, data remains encrypted and unavailable while the device is locked. If your app needs to access encrypted data to perform a task, you likely need to set this property to YEStrue to ensure that the data is accessible.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the action is destructive. (read-only)

    Declaration

    Swift

    var destructive: Bool { get }

    Objective-C

    @property(nonatomic, assign, readonly, getter=isDestructive) BOOL destructive

    Discussion

    Use this property to signal to the user whether the action causes destructive behavior to the user’s data or the app. When the value of this property is YEStrue, the system displays the corresponding button differently to indicate that the action is destructive.

    The default value of this property is NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • The custom behavior (if any) that the action supports. (read-only)

    Declaration

    Swift

    var behavior: UIUserNotificationActionBehavior { get }

    Objective-C

    @property(nonatomic, assign, readonly) UIUserNotificationActionBehavior behavior

    Discussion

    The default value of this property is UIUserNotificationActionBehaviorDefault.

    Availability

    Available in iOS 9.0 and later.

  • A dictionary of additional parameters to include with the action. (read-only)

    Declaration

    Swift

    var parameters: [NSObject : AnyObject] { get }

    Objective-C

    @property(nonatomic, copy, readonly) NSDictionary *parameters

    Discussion

    Use this dictionary to specify any behavior-specific data for the action. For example, the UIUserNotificationActionBehaviorTextInput behavior supports the UIUserNotificationTextInputActionButtonTitleKey key, which lets you customize the title of the button displayed by the text input interface.

    Availability

    Available in iOS 9.0 and later.

  • Constants indicating whether the app should activate to the foreground or background.

    Declaration

    Swift

    enum UIUserNotificationActivationMode : UInt { case Foreground case Background }

    Objective-C

    typedef enum UIUserNotificationActivationMode : NSUInteger { UIUserNotificationActivationModeForeground, UIUserNotificationActivationModeBackground } UIUserNotificationActivationMode;

    Constants

    • Foreground

      UIUserNotificationActivationModeForeground

      Activate the app and put it in the foreground.

      Available in iOS 8.0 and later.

    • Background

      UIUserNotificationActivationModeBackground

      Activate the app and put it in the background. If the app is already in the foreground, it remains in the foreground.

      Available in iOS 8.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Constants indicating additional behavior that the action supports.

    Declaration

    Swift

    enum UIUserNotificationActionBehavior : UInt { case Default case TextInput }

    Objective-C

    typedef enum UIUserNotificationActionBehavior : NSUInteger { UIUserNotificationActionBehaviorDefault, UIUserNotificationActionBehaviorTextInput } UIUserNotificationActionBehavior;

    Constants

    • Default

      UIUserNotificationActionBehaviorDefault

      The default action behavior. When specified, the action supports no additional behaviors.

      Available in iOS 9.0 and later.

    • TextInput

      UIUserNotificationActionBehaviorTextInput

      The text input behavior. When specified, the system provides a way for the user to enter a text response to be included with the notification. The text response is assigned to the UIUserNotificationActionResponseTypedTextKey of the response information dictionary when the notification is delivered to your app.

      Available in iOS 9.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 9.0 and later.

  • Key to include among the parameters of the action.

    Declaration

    Swift

    let UIUserNotificationTextInputActionButtonTitleKey: String

    Objective-C

    NSString *const UIUserNotificationTextInputActionButtonTitleKey;

    Constants

    • UIUserNotificationTextInputActionButtonTitleKey

      UIUserNotificationTextInputActionButtonTitleKey

      The key for specifying the title of the text input button. The value of this key is an NSString object. When the user chooses to provide a text response to a notification, UIKit displays an interface for entering that response. The value of this key is used on the button that the user taps to accept that text and attach it to the notification.

      Available in iOS 9.0 and later.

  • Key related to action-related behaviors.

    Declaration

    Swift

    let UIUserNotificationActionResponseTypedTextKey: String

    Objective-C

    NSString *const UIUserNotificationActionResponseTypedTextKey;

    Constants

    • UIUserNotificationActionResponseTypedTextKey

      UIUserNotificationActionResponseTypedTextKey

      The response text selected by the user. The value of this key is an NSString containing the user-specified text. When the user enters a text response for a notification, the text is added to a dictionary and delivered along with the notification. Use this key to access to the response in that dictionary.

      Available in iOS 9.0 and later.