UILocalNotification Tutorial – How to Notify Users

Reading through recent comments, a few of you have asked how to get local notifications working on your iOS apps. Local Notifications are the one that pop up on your lock screen and give you information such as when an alarm goes off or a calendar item becomes due. If you are using your iPhone, they also drop down from the top of the screen for a few seconds. Types of apps that use this feature could include calendars, todo lists, games and any other type of app that might want to inform a user that some action could be taken or that some information is available. An example of a local notification was used in the Background App Refresh tutorial recently. In todays tutorial, we’ll show you in more detail how this is done.

Local Notifications make use of a class called UILocalNotification in the UIKit framework. By configuring the properties of UILocalNotification, you can use the UIApplication class to trigger the notification to arrive on screen either immediately or at a specified time and date. UIApplication handles putting the notification on the screen when required.

Todays tutorial will be brief and will simply let you select a date and time to fire a notification. The code to achieve this can be implemented in many situations such as on a location based app that fires a notification when you enter within range of a recognised iBeacon or when you enter a specified region.

UILocalNotification Tutorial

Lets start by creating a Single View Application. When created, load up the Storyboard as seen on the image to the left.

When loaded up, we need to drag out a UIButton and a UIDatePicker. The button will be used to set the notification going and the UIDatePicker will be used to set the date/time that the notification should be fired. The layout is very simple the purpose of this tutorial:

Now that you have the UIDatePicker on screen, you need to make some tweaks to the settings using the inspector. To do that, click on the UIDatePicker to select it and then click to Show the Attributes Inspector as seen below:

Here we select Date and Time, Default Locale, Interval 1 minute, Date as current date and leave the rest as it is. Feel free to set this however you want. You can opt for 30 minute intervals if you wish. It’s up to you how you do this.

Next we need to show the Assistant Editor which allows us to see both the Storyboard and the Implementation side by side. This allows us to CTRL+Drag to connect up the IBActions that we need to allow the user to interact with the application.

CTRL+drag from the UIDatePicker to the implementation. I called the IBAction datePicker and selected UIDatePicker as the type.

Now do the same for the UIButton. I called it setNotification and set the type as UIButton.

We now need to implement the code that will make this work. Lets start with the datePicker method as we need to provide an NSDate to the UILocalNotification so that we can set when the notification will be fired.

NSDate *dateTime;

- (IBAction)datePicker:(UIDatePicker *)sender {
    dateTime = sender.date;
}

The first line of code in the above block can go under the @implementation line. Declaring it here makes it accessible by other methods in this class.

The only line of code we need to add to the datePicker: method is to use the sender.date property and assign it to dateTime. The UIDatePicker provides an NSDate and the UILocalNotification requires an NSDate which makes this process simple.

Moving on to the setNotification: method, there are several lines of code that need adding so that we can configure the notification and tell it when to fire as well as tell it what should be displayed on screen.

- (IBAction)setNotification:(UIButton *)sender {
    UILocalNotification *localNotification = [[UILocalNotification alloc] init];
    localNotification.fireDate = dateTime;
    localNotification.alertBody = [NSString stringWithFormat:@"Alert Fired at %@", dateTime];
    localNotification.soundName = UILocalNotificationDefaultSoundName;
    localNotification.applicationIconBadgeNumber = 1;
    [[UIApplication sharedApplication] scheduleLocalNotification:localNotification];
}

Line 2 we alloc/init a UILocalNotification.

Line 3 we set the fireDate property. We do that with the dateTime we collected from the UIDatePicker. The fireDate is exactly what it sounds like… the date that the notification will fire.

Line 4 we set the alertBody. This is the text that appears on screen in the notification (either on the lock screen or as a banner depending on if your phone is locked or unlocked). By default, the name of the alert will be the name of your app. The text can be whatever you want and formated with the class method stringWithFormat: so that you can pull in information such as the dateTime. If you were alerting about a calendar event or task you might want to pull in information such as the appointment name and time.

Line 5 we set the soundName property. Here we assigned that property the default sound name (the regular chime).

Line 6 isn’t really required here, but what you could do is set the applicationIconBadgeNumber. This needs to be an INT. Anything set here will display as a number in a red circle on the top right of the icon.

Line 7 is where we schedule the local notification. As we are using the UIApplication class as a sharedApplication, we first access that and then call the scheduleNotification: method on that.

The app is now ready to run. If you set up several alerts they will all be presented at the specified date and time. All notifications are queued up and fire at the times specified although note that if your app is currently running then triggered alerts will not show or make a sound. They are simply ignored under this configuration. We’ll take a look in a few moments how to get around that.

Lets now quickly look at the presentLocalNotificationNow: method in the UIApplication class. This method is different to the scheduleLocalNotification: method. As the name suggests, it fires the alert right now.

Uses for this would include entering a region and immediately notifying the user that they have entered a region on a map. When you enter a region, you don’t need to be alerted at a specific time… you need to be notified now. Using this method avoids you having to use an NSDate or setting the fireDate property as they are not needed and ignored.

Going back to my comment about notifications not showing when the app is running, we can actually address this using a delegate method in the AppDelegate as follows:

-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    
}

If a notification fires when you are using the app, instead of being notified, the method above is called. At this point it is up to you how you inform the user that a notification has happened. Perhaps you will put a message on the screen or perhaps cause a UIAlert to show on the view. Either way, this delegate method lets you know what UILocalNotification was going to be presented and here you could get the alertBody by accessing notification.alertBody.

The full code of this project is below or can be downloaded here.

ViewController.h – No changes needed from default.

ViewController.m

#import "ViewController.h"

@interface ViewController ()

@end

@implementation ViewController

NSDate *dateTime;

- (void)viewDidLoad
{
    [super viewDidLoad];
	// Do any additional setup after loading the view, typically from a nib.
}

- (IBAction)setNotification:(UIButton *)sender {
    UILocalNotification *localNotification = [[UILocalNotification alloc] init];
    localNotification.fireDate = dateTime;
    localNotification.alertBody = [NSString stringWithFormat:@"Alert Fired at %@", dateTime];
    localNotification.soundName = UILocalNotificationDefaultSoundName;
    localNotification.applicationIconBadgeNumber = 1;
    [[UIApplication sharedApplication] scheduleLocalNotification:localNotification];
}

- (IBAction)datePicker:(UIDatePicker *)sender {
    dateTime = sender.date;
    NSLog(@"Date is %@", dateTime);
}

- (void)didReceiveMemoryWarning
{
    [super didReceiveMemoryWarning];
    // Dispose of any resources that can be recreated.
}

@end

AppDelegate.m
Just implement the following delegate method:

-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    
}