iOS Developer Library — Pre-Release

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.

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 4.0 and later.
  • fireDate fireDate Property

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • timeZone timeZone Property

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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 an calendar unit such as weekly (NSWeekCalendarUnit) or yearly (NSYearCalendarUnit), the system reschedules the notification for delivery at the specified interval. The default value is 0, which means that the system fires the notification once and then discards it.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • region region Property

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • alertBody alertBody Property

    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 (%%).

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.2 and later.

  • hasAction hasAction Property

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • category category Property

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The number to display as the app’s icon badge.

    Declaration

    Swift

    var applicationIconBadgeNumber: Int

    Objective-C

    @property(nonatomic) NSInteger applicationIconBadgeNumber

    Discussion

    The default value of this property is 0, which means that no badge is displayed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • soundName soundName Property

    The name of the file containing the sound to play when an alert is displayed.

    Declaration

    Swift

    var soundName: String?

    Objective-C

    @property(nonatomic, copy) NSString *soundName

    Discussion

    For this property, specify the filename (including extension) of a sound resource in the app’s main bundle or UILocalNotificationDefaultSoundName to request the default system sound. When the system displays an alert for a local notification or badges an app icon, it plays this sound. The default value is nil (no sound). Sounds that last longer than 30 seconds are not supported. If you specify a file with a sound that plays over 30 seconds, the default sound is played instead.

    For information on valid sound resources, see Scheduling, Registering, and Handling Notifications in Local and Remote Notification Programming Guide.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • userInfo userInfo Property

    A dictionary for passing custom information to the notified app.

    Declaration

    Swift

    var userInfo: [NSObject : AnyObject]?

    Objective-C

    @property(nonatomic, copy) NSDictionary *userInfo

    Discussion

    You may add arbitrary key-value pairs to this dictionary. However, the keys and values must be valid property-list types; if any are not, an exception is raised.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.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.