Scheduling Notifications

Local notifications give you a way to alert the user at times when your app might not be running. You schedule local notifications at the time when your app is running either in the foreground or background. After scheduling a notification, the system takes on the responsibility of delivering the notification to the user at the appropriate time. Your app does not need to be running for the system to deliver the notification.

If your app is not running, or if it is in the background, the system displays local notifications directly to the user. The system can alert the user with an alert panel or banner, with a sound, or by badging your app’s icon. If your app provides a notification content app extension, the system can even use your custom interface to alert the user. If your app is in the foreground when a notification arrives, the system gives your app the opportunity to handle the notification internally.

Configuring a Local Notification

The steps for configuring a local notification are as follows:

  1. Create and configure a ISN_UNNotificationContent object with the notification details.

  2. Create a ISN_UNCalendarNotificationTriggerISN_UNTimeIntervalNotificationTrigger, or ISN_UNLocationNotificationTrigger  object to describe the conditions under which the notification is delivered.

  3. Create a ISN_UNNotificationRequest object with the content and trigger information.

  4. Call the AddNotificationRequest method to schedule the notification; see Scheduling Local Notifications for Delivery

When creating the content for a notification, fill in the properties of the ISN_UNNotificationContent object that reflect the type of interaction you want with the user. For example, fill in the title and body properties when you want to display an alert. The system uses the information you provide to determine how to interact with the user. You can also use the data in this object when handling a local notification that has been delivered to your app.

After creating the notification content, create a trigger object that defines when to deliver the notification. The User Notifications framework provides both time-based and location-based triggers. Configure the trigger with the required conditions and use that object plus your content to create the ISN_UNNotificationRequest object.

The code snippet below shows how to create and configure a local notification related to an alarm. The use of a ISN_UNCalendarNotificationTrigger causes the notification to be delivered at a specific date or time, which in this example is the next time the clock reaches 7:00 in the morning.

using SA.IOSNative.Foundation;
using SA.IOSNative.UserNotifications;
...
var content = new ISN_UNNotificationContent();
content.Title = "Wake up!";
content.Body = "Rise and shine! It's morning time!";

ISN_NSDateComponents date = new ISN_NSDateComponents();
date.Hour = 7;
date.Minute = 0;


var trigger = new ISN_UNCalendarNotificationTrigger(date, false);

// Create the request object.
string identifier = "MorningAlarm";
var request = new ISN_UNNotificationRequest(identifier, content, trigger)

Providing an identifier for the ISN_UNNotificationRequest object gives you a way to identify local notifications after they have been scheduled. You can use identifiers to look up pending requests later and to cancel them before they are delivered. For more information on scheduling and canceling requests, see Scheduling Local Notifications for Delivery.

Adding a Sound to the Notification Content

If you want a local notification to play a sound when it is delivered, assign a value to the sound property of your ISN_UNNotificationContent object. You specify sounds using a ISN_UNNotificationSound object, which lets you play either a custom sound or the default notification sound. Custom sounds must be added to the XCode project before they can be played. You may add sounds to Xcode project using the IOS Deploy settings.

Stan's Assets -> IOS Deploy -> Settings

To play the default sound, create the sound file and assign it to your notification content. For example:

content.Sound = ISN_UNNotificationSound.DefaultSound;

When specifying custom sounds, specify only the filename of the sound file that you want to be played. If the system finds a suitable sound file with the name you provided, it plays that sound when delivering the notification. If the system does not find a suitable sound file, it plays the default sound.

content.Sound = ISN_UNNotificationSound.SoundNamed("MySound.wav");

Scheduling Local Notifications for Delivery

To schedule a local notification for delivery, create your ISN_UNNotificationRequest object and call the AddNotificationRequest method of ISN_UNUserNotificationCenter. The system schedules local notifications asynchronously, calling your callback block when scheduling is complete or when an error occurs. The code snippet below shows how to schedule a local notification for delivery. The code in this example completes the scheduling of the notification created in the previous chapter.

using SA.IOSNative.UserNotifications;
...
ISN_UNUserNotificationCenter.AddNotificationRequest(request, (result) => {
    if(result.IsSucceeded) {
        Debug.Log("Notification Request Added. ");
    } else {
        Debug.Log("Error: " + result.Error.Message);
    }
});

Scheduled local notifications remain active until they are unscheduled by the system or until you cancel them explicitly. The system unschedules notifications automatically after they are delivered unless the notification’s trigger is configured to repeat. To cancel an individual notification before it is delivered, or to cancel a repeating notification, call the RemovePendingNotificationRequests method of ISN_UNUserNotificationCenter. The notification being canceled must have an identifier assigned to its ISN_UNNotificationRequest object. To cancel all pending local notifications, regardless of whether they have a request identifier, call the RemoveAllPendingNotificationRequests method instead.