iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UILocalNotification Class Reference

Options
Deployment Target:

On This Page
Language:

UILocalNotification

A UILocalNotification object specifies a notification that an app can schedule for presentation at a specific date and time. The operating system is responsible for delivering local notifications at their scheduled times; the app does not have to be running for this to happen. Although local notifications are similar to remote notifications in that they are used for displaying alerts, playing sounds, and badging app icons, they are composed and delivered locally and do not require connection with remote servers.

Local notifications are primarily intended for apps with timer-based behaviors and simple calendar or to-do list apps. An app that is running in the background may also schedule a local notification to inform the user of an incoming message, chat, or update. An app can have only a limited number of scheduled notifications; the system keeps the soonest-firing 64 notifications (with automatically rescheduled notifications counting as a single notification) and discards the rest.

When you create a local notification, you must specify either a specific date or a geographic region as the trigger for delivering the notification. Date-based notifications are delivered at the day and time you specify, and allowances can be made for time zone changes as needed. Region-based notifications are delivered when the user enters or exits the specified region. In both cases, you can specify whether the notifications are one-time events or can be rescheduled and delivered again.

After creating a UILocalNotification object, schedule it using either the scheduleLocalNotification: or presentLocalNotificationNow: method of the UIApplication class. The scheduleLocalNotification: method uses the fire date to schedule delivery; the presentLocalNotificationNow: method presents the notification immediately, regardless of the value of fireDate. You can cancel one or more local notifications using the cancelLocalNotification: or cancelAllLocalNotifications method of the UIApplication object.

When the system delivers a local notification, several things can happen, depending on the app state and the type of notification. If the app is not frontmost and visible, the system displays the alert message, badges the app, and plays a sound—whatever is specified in the notification. If the notification is an alert and the user taps the action button (or, if the device is locked, drags open the action slider), the app is woken up or launched. (If the user taps one of the custom actions you specify using the additionalActions property, the app is woken up or launched into the background.) In its application:didFinishLaunchingWithOptions: method, the app delegate can obtain the UILocalNotification object from the launch options dictionary using the UIApplicationLaunchOptionsLocalNotificationKey key. The delegate can inspect the properties of the notification and, if the notification includes custom data in its userInfo dictionary, it can access that data and process it accordingly. On the other hand, if the local notification only badges the app icon, and the user in response launches the app, the application:didFinishLaunchingWithOptions: method is called, but no UILocalNotification object is included in the options dictionary. When the user selects a custom action, the app delegate’s application:handleActionWithIdentifier:forLocalNotification:completionHandler: method is called to handle the action.

If the app is foremost and visible when the system delivers the notification, the app delegate’s application:didReceiveLocalNotification: is called to process the notification. Use the information in the provided UILocalNotification object to decide what action to take. The system does not display any alerts, badge the app’s icon, or play any sounds when the app is already frontmost.

An app is responsible for managing the badge number displayed on its icon. For example, if a text-messaging app processes all incoming messages after receiving a local notification, it should remove the icon badge by setting the applicationIconBadgeNumber property of the UIApplication object to 0.

  • The date and time when the system should deliver the notification.

    Declaration

    Swift

    @NSCopying var fireDate: NSDate?

    Objective-C

    @property(nonatomic, copy) NSDate *fireDate

    Discussion

    The fire date is interpreted according to the value specified in the timeZone property. If the specified value is nil or is a date in the past, the notification is delivered immediately.

    You may specify a value for this property or the region property but not both. Attempting to schedule a local notification that contains both a region and fire date raises an exception.

    Availability

    Available in iOS 4.0 and later.

  • The time zone of the notification’s fire date.

    Declaration

    Swift

    @NSCopying var timeZone: NSTimeZone?

    Objective-C

    @property(nonatomic, copy) NSTimeZone *timeZone

    Discussion

    The date specified in fireDate is interpreted according to the value of this property. If you specify nil (the default), the fire date is interpreted as an absolute GMT time, which is suitable for cases such as countdown timers. If you assign a valid NSTimeZone object to this property, the fire date is interpreted as a wall-clock time that is automatically adjusted when there are changes in time zones; an example suitable for this case is an an alarm clock.

    Availability

    Available in iOS 4.0 and later.

  • The calendar interval at which to reschedule the notification.

    Declaration

    Swift

    var repeatInterval: NSCalendarUnit

    Objective-C

    @property(nonatomic) NSCalendarUnit repeatInterval

    Discussion

    If you assign a calendar unit such as weekly (NSWeekCalendarUnit) or yearly (NSYearCalendarUnit), the system reschedules the notification for delivery at the specified interval. Note that intervals of less than one minute are not supported. The default value is 0, which means that the system fires the notification once and then discards it.

    Availability

    Available in iOS 4.0 and later.

  • The calendar the system should refer to when it reschedules a repeating notification.

    Declaration

    Swift

    @NSCopying var repeatCalendar: NSCalendar?

    Objective-C

    @property(nonatomic, copy) NSCalendar *repeatCalendar

    Discussion

    The default value is nil, which indicates that the current user calendar is used. (The current user calendar is returned by the currentCalendar class method of NSCalendar.)

    Availability

    Available in iOS 4.0 and later.

  • The geographic region that triggers the notification.

    Declaration

    Swift

    @NSCopying var region: CLRegion?

    Objective-C

    @property(nonatomic, copy) CLRegion *region

    Discussion

    Assigning a value to this property causes the local notification to be delivered when the user crosses the region’s boundary. The region object itself defines whether the notification is triggered when the user enters or exits the region. The default value of this property is nil.

    You may specify a value for this property or the fireDate property but not both. Attempting to schedule a local notification that contains both a region and fire date raises an exception.

    Apps are limited in the total number of regions they may monitor at any given time, and local notifications configured with a region value count against that total. In addition, the user must grant permission for your app to use location-related information for the delivery of region-based local notifications to work. If the user denies your app’s request to use location services, local notifications configured with a region will not be delivered.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether crossing a geographic region boundary delivers only one notification.

    Declaration

    Swift

    var regionTriggersOnce: Bool

    Objective-C

    @property(nonatomic, assign) BOOL regionTriggersOnce

    Discussion

    When the value of this property is YEStrue, the user is notified only upon the first crossing the boundary of the target region. After the first crossing, the local notification is unscheduled. When the value of this property is NOfalse, notifications are delivered with each boundary crossing. The default value of this property is YEStrue.

    The region object itself defines whether the notification is triggered when the user enters or exits the region.

    Availability

    Available in iOS 8.0 and later.

  • The message displayed in the notification alert.

    Declaration

    Swift

    var alertBody: String?

    Objective-C

    @property(nonatomic, copy) NSString *alertBody

    Discussion

    Assign a string or, preferably, a localized-string key (using NSLocalizedString) as the value of the message. If the value of this property is non-nil, an alert is displayed. The default value is nil (no alert). Printf style escape characters are stripped from the string prior to display; to include a percent symbol (%) in the message, use two percent symbols (%%).

    Availability

    Available in iOS 4.0 and later.

  • The title of the action button or slider.

    Declaration

    Swift

    var alertAction: String?

    Objective-C

    @property(nonatomic, copy) NSString *alertAction

    Discussion

    Assign a string or, preferably, a localized-string key (using NSLocalizedString) as the value. The alert action is the title of the right button of the alert or the value of the unlock slider, where the value replaces “unlock” in “slide to unlock”. If you specify nil, and alertBody is non-nil, “View” (localized to the preferred language) is used as the default value.

    Availability

    Available in iOS 4.0 and later.

    See Also

    hasAction

  • A short description of the reason for the alert.

    Declaration

    Swift

    var alertTitle: String?

    Objective-C

    @property(nonatomic, copy) NSString *alertTitle

    Discussion

    Use this property to provide a short description of the reason for the alert. You may specify a string with the text you want to display or you may specify a string to use as a lookup key in your app’s Localizable.strings file. The default value of this property is nil.

    Title strings should be short, usually only a couple of words describing the reason for the notification. Apple Watch displays the title string as part of the short look notification interface, which has limited space.

    Availability

    Available in iOS 8.2 and later.

  • A Boolean value that controls whether the notification shows or hides the alert action.

    Declaration

    Swift

    var hasAction: Bool

    Objective-C

    @property(nonatomic) BOOL hasAction

    Discussion

    Assign NOfalse to this property to hide the alert button or slider. (This effect requires alertBody to be non-nil.) The default value is YEStrue.

    Availability

    Available in iOS 4.0 and later.

    See Also

    alertAction

  • Identifies the image used as the launch image when the user taps (or slides) the action button (or slider).

    Declaration

    Swift

    var alertLaunchImage: String?

    Objective-C

    @property(nonatomic, copy) NSString *alertLaunchImage

    Discussion

    The string is a filename of an image file in the app bundle. This image is a launching image specified for a given notification; when the user taps the action button (for example, “View”) or moves the action slider, the image is used in place of the default launching image. If the value of this property is nil (the default), the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the app’s Info.plist file, or falls back to Default.png.

    The value of this key has the exact same semantics as UILaunchImageFile. For more about this key, see the Information Property List Key Reference.

    Availability

    Available in iOS 4.0 and later.

  • The name of a group of actions to display in the alert.

    Declaration

    Swift

    var category: String?

    Objective-C

    @property(nonatomic, copy) NSString *category

    Discussion

    The value of this property is the category name associated with a registered UIUserNotificationSettings object. When the alert for the local notification is displayed, the system uses the string you specify to look up the group and retrieve its actions. It then adds a button to the alert for each action defined by the group. When the user taps one of those buttons, the app is woken up (or launched) and given a chance to perform the designated action. If the specified category name does not belong to a registered group of actions, the alert does not display any additional action buttons.

    Specifying custom actions is optional. The value of this property is nil by default.

    Availability

    Available in iOS 8.0 and later.

  • The default system sound for local notifications.

    Declaration

    Swift

    let UILocalNotificationDefaultSoundName: String

    Objective-C

    UIKIT_EXTERN NSString *const UILocalNotificationDefaultSoundName;

    Constants

    • UILocalNotificationDefaultSoundName

      UILocalNotificationDefaultSoundName

      Identifies the default system sound to play when a notification alert is displayed. You assign this value to the soundName property.

      Available in iOS 4.0 and later.