Local Notifications

Local notifications and remote notifications are two types of user notifications. (Remote notifications are also known as push notifications.) Both types of user notifications enable an app that isn’t running in the foreground to let its users know that it has information for them. The information could be a message, an impending calendar event or new data on a remote server. When presented by the operating system, local and remote user notifications look and sound the same. They can display an alert message or they can badge an app icon. They can also play a sound when the alert or badge number is shown.

When users are notified that the app has a message, event or another data for them, they can launch the app and see the details. They can also choose to ignore the notification. In this case the app is not activated.

Requesting User Permission

Starting from IOS8 we need to request permissions in order to send local notifications to the user. It’s recommended to do while launching your app, but it’s up to you.

You can do this by using the following function:

int notificationTypes = ISN_NotificationType.Alert | ISN_NotificationType.Sound | ISN_NotificationType.Badge;
ISN_LocalNotificationsController.Instance.RequestNotificationPermissions(notificationTypes);
 

However, you can skip this step. In this case a permission is requested when you try to Schedule your first Notification.

Note: User will be asked only once. All other attempts to request permission will be ignored by IOS. User can always change app notification setting under device settings menu. As the workaround, you may use Shared Url API to prompt the user to change app setting and open iOS setting application.

Scheduling notifications

Here is an example how can Scheduling notification using ISN_LocalNotification object with will be fired in 5 seconds, and find out if it was successfully  scheduled + get currently allowed notifications types:

Listener for the scheduling result:

ISN_LocalNotificationsController.OnNotificationScheduleResult += OnNotificationScheduleResult;
 
ISN_LocalNotification notification =  new ISN_LocalNotification(DateTime.Now.AddSeconds(5),"Your Notification Text No Sound", false);
notification.Schedule();


private void OnNotificationScheduleResult (ISN_Result res) {
	ISN_LocalNotificationsController.OnNotificationScheduleResult -= OnNotificationScheduleResult;
        
    string msg = string.Empty;
         
    if(res.IsSucceeded) {
        msg = "Notification was successfully scheduled";    
    } else {
        msg = "Notification scheduling failed";
    }
    
    IOSMessage.Create("Notification Schedule Result", msg);
}

You can also specify additional notification data and badges as showed on the snippet below.

ISN_LocalNotification notification =  new ISN_LocalNotification(DateTime.Now.AddSeconds(5),"Your Notification Text", true);
notification.SetData("some_test_data");
notification.SetBadgesNumber(1);
notification.Schedule();

Using custom sound

If you want to add custom sound to your notification, you need to complete 2 simple steps.

1) Set full sound file name during creating the ISN_LocalNotification object. Code snippet is below.

ISN_LocalNotification notification =  new ISN_LocalNotification(DateTime.Now.AddSeconds(5),"Your Notification Text", true);
notification.SetData("some_test_data");

notification.SetSoundName("purchase_ok.wav");

notification.SetBadgesNumber(1);
notification.Schedule();

2) When build process is complete, add sound file to the Xcode project budle as showed on the screenshot below.

Canceling notifications

If you want cancel the notification, you can do this by canceling specific notification using its id or ISN_LocalNotification object with the following methods of  IOSNotificationController

public void CancelLocalNotification (ISN_LocalNotification notification);
public void CancelLocalNotificationById (int notificationId);

Or you can cancel all scheduled notifications:

ISN_LocalNotificationsController.Instance.CancelAllLocalNotifications();

If you used notifications with badges, you can clear badges number using:

IOSNativeUtility.SetApplicationBagesNumber(0);

To find out pending notification list, use:

List<ISN_LocalNotification> PendingNotofications;
PendingNotofications = IOSNotificationController.Instance.LoadPendingNotifications();

Notification events

If your app has been launched from the notification, you get the notification object from the LaunchNotification getter. If you app has been launched normally, the LaunchNotification  will remain null. Code snippet below shows how to check if app has been launched from the local notification and print notification data.

if(ISN_LocalNotificationsController.Instance.LaunchNotification != null) {
	ISN_LocalNotification notification = IOSNotificationController.Instance.LaunchNotification;
	IOSMessage.Create("Launch Notification", "Messgae: " + notification.Message + "\nNotification Data: " + notification.Data);
}

If a user restored an application from the background, or notification was received while app is in the foreground, you can handle this case by subscribing to the Action<ISN_LocalNotification>  OnLocalNotificationReceived Action. 

IOSNotificationController.OnLocalNotificationReceived += HandleOnLocalNotificationReceived;

void HandleOnLocalNotificationReceived (ISN_LocalNotification notification) {
	IOSMessage.Create("Notification Received", "Messgae: " + notification.Message + "\nNotification Data: " + notification.Data);
}

Retrieving current notification settings

A code snippet below shows how to retrieve current notification settings, for example, to check if a sound is available:

int avaliableTypes = ISN_LocalNotificationsController.CurrentNotificationsSettings;
IOSMessage.Create("Current Notifications Settins: ",  avaliableTypes.ToString ());


if((avaliableTypes & ISN_NotificationType.Sound) != 0) {
    Debug.Log ("ISN_NotificationType.Sound avaliable");
}


if((avaliableTypes & ISN_NotificationType.Badge) != 0) {
    Debug.Log ("ISN_NotificationType.Badge avaliable");
}


if((avaliableTypes & ISN_NotificationType.Alert) != 0) {
    Debug.Log ("ISN_NotificationType.Alert avaliable");
}

API Reference

IOSNotificationController

public class ISN_LocalNotificationsController : ISN_Singleton<IOSNotificationController> {
	
	//--------------------------------------
	//  Actions
	//--------------------------------------

	public static event Action<Result>  OnNotificationScheduleResult = delegate {};
	public static event Action<ISN_LocalNotification>  OnLocalNotificationReceived = delegate {};

	//--------------------------------------
	//  Public Methods
	//--------------------------------------

	public void RequestNotificationPermissions(int types);
	public void ShowGameKitNotification (string title, string message);
	public void CancelAllLocalNotifications ();
	public void CancelLocalNotification (ISN_LocalNotification notification);
	public void CancelLocalNotificationById (int notificationId);
	public void ApplicationIconBadgeNumber (int badges);

	//--------------------------------------
	//  Get / Set
	//--------------------------------------

	public static int CurrentNotificationsSettings {get;}
	public ISN_LocalNotification LaunchNotification {get;}
}

ISN_LocalNotification

public class ISN_LocalNotification  {

	//--------------------------------------
	// Constructor
	//--------------------------------------

	public ISN_LocalNotification(DateTime time, string message, bool useSound = true);

	//--------------------------------------
	// Public Methods
	//--------------------------------------

	public void SetData(string data);
    public void SetSoundName(string soundName);
	public void SetBadgesNumber(int badges);
	public void Schedule();

	//--------------------------------------
	// Get / Set
	//--------------------------------------

	public int Id {get;}
    public string SoundName {get;}
	public DateTime Date {get;}
	public string Message {get;}
	public bool UseSound {get;}
	public int Badges {get;}
	public string Data {get;}
}