Class

UILocalNotification

Important:UILocalNotification is deprecated in iOS 10. Use UNNotificationRequest instead. A UILocalNotification object specifies a notification that an app can schedule for presentation at a specific date and time.

Declaration

@interface UILocalNotification : NSObject

Overview

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

Topics

Scheduling a Local Notification

fireDate

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

timeZone

The time zone of the notification’s fire date.

repeatInterval

The calendar interval at which to reschedule the notification.

repeatCalendar

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

region

The geographic region that triggers the notification.

regionTriggersOnce

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

Composing the Alert

alertBody

The message displayed in the notification alert.

alertAction

The title of the action button or slider.

alertTitle

A short description of the reason for the alert.

hasAction

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

alertLaunchImage

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

category

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

Configuring Other Parts of the Notification

applicationIconBadgeNumber

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

soundName

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

userInfo

A dictionary for passing custom information to the notified app.

Constants

Notification Sound

The default system sound for local notifications.

Relationships

Inherits From

Conforms To

See Also

Deprecated Classes

UIPreviewAction

A preview action, or peek quick action, that is displayed below a peek when a user swipes the peek upward.

Deprecated
UIPreviewActionGroup

A group of one or more child quick actions, each an instance of the UIPreviewAction class.

Deprecated
UICommandGroup

An object containing a group of commands and other groups.

Deprecated
UIAcceleration

An instance of the UIAcceleration class, called an acceleration event, represents immediate, three-dimensional acceleration data. To receive accelerometer events, register an application object as a delegate of the shared UIAccelerometer object, as described in UIAccelerometer.

Deprecated
UIAccelerometer

The UIAccelerometer class lets you register to receive acceleration-related data from the onboard hardware. As a device moves, its hardware reports linear acceleration changes along the primary axes in three-dimensional space. You can use this data to detect both the current orientation of the device (relative to the ground) and any instantaneous changes to that orientation. You might use instantaneous changes as input to a game or to initiate some action in your application.

Deprecated
UIActionSheet

Important: UIActionSheet is deprecated in iOS 8. (Note that UIActionSheetDelegate is also deprecated.) To create and manage action sheets in iOS 8 and later, instead use UIAlertController with a preferredStyle of UIAlertControllerStyleActionSheet.

Deprecated
UIAlertView

In apps that run in versions of iOS prior to iOS 8, use the UIAlertView class to display an alert message to the user. An alert view functions similar to but differs in appearance from an action sheet (an instance of UIActionSheet).

Deprecated
UIDocumentMenuViewController

A list of all the available document providers for a given file type and mode, in addition to custom menu items that you add.

Deprecated
UIMutableUserNotificationAction

Important: UIMutableUserNotificationAction is deprecated in iOS 10. Use UNNotificationAction instead. A UIMutableUserNotificationAction object represents a modifiable version of the UIUserNotificationAction class.

Deprecated
UIMutableUserNotificationCategory

Important: UIMutableUserNotificationCategory is deprecated in iOS 10. Use UNNotificationCategory instead. A UIMutableUserNotificationCategory object encapsulates information about custom actions that your app can perform in response to a local or push notification. Use instances of this class to customize the actions included in an alert when space onscreen is constrained.

Deprecated
UIPopoverController

Important: UIPopoverController is deprecated in iOS 9. In iOS 9 and later, a popover is implemented as a UIViewController presentation. To create a popover, use an instance of UIPopoverPresentationController and specify the UIModalPresentationPopover style.

Deprecated
UISearchDisplayController

Important: UISearchDisplayController is deprecated in iOS 8. (Note that UISearchDisplayDelegate is also deprecated.) To manage the presentation of a search bar and display search results in iOS 8 and later, instead use UISearchController.

Deprecated
UIStoryboardPopoverSegue

The UIStoryboardPopoverSegue class defines a specific type of segue for presenting content in a popover. For popover segues, the destination view controller contains the content to be displayed in the popover. This class provides an additional popoverController property so that your custom code has access to the popover controller object. For example, you might want to store the popover controller elsewhere in your code so that you can dismiss the popover programmatically.

Deprecated
UIUserNotificationAction

Important: UIUserNotificationAction is deprecated in iOS 10. Use UNNotificationAction instead. A UIUserNotificationAction object represents a custom action that your app can perform in response to a remote or local notification.

Deprecated
UIUserNotificationCategory

Important:UIUserNotificationCategory is deprecated in iOS 10. Use UNNotificationCategory instead. A UIUserNotificationCategory object encapsulates information about custom actions that your app can perform in response to a local or push notification.

Deprecated
UIUserNotificationSettings

Important: UIUserNotificationSettings is deprecated in iOS 10. Use UNNotificationSettings instead. A UIUserNotificationSettings object encapsulates the types of notifications that can be displayed to the user by your app.

Deprecated