Page tree
Skip to end of metadata
Go to start of metadata

The Local Notifications alert the user even if your application is not running. The reason of the local notifications is to inform the user that something interesting has happened while the application was not running in the foreground.

The Local Notifications work with schedules, like calendar and to-do list apps. You can also use multitasking applications to support updates when the application is closed. For example, a location-based app might pop up a notification to let a user know that the app has detected that the user is near the local library and the books that he requested are ready to be picked up.

Actually, your app doesn’t trigger local notification alert; the system does. You set the system instructions for when the local notification is to fire, and let the system deal with it. That’s why, the local notifications can appear even if your app isn’t active or isn’t even running. Indeed, if your app is active, the local notification’s alert view or banner does not automatically appear when it fires; instead, your app is notified, and you can notify the user if you like. The only local notification alert view that can appear when your app is active is some local notifications of other applications.

       

The Local Notification object of the Smartface has the properties as follows:

Common Properties

alertBody
The message displayed in the notification.

alertAction
This matters only if your notification is displayed as an alert; in that case, this is the text of the action button.

sound
The name of a sound file at the top level of your app bundle, to be played when the alert appears. This should be an uncompressed sound (AIFF or WAV). If you don’t set this property, there won’t be any sound.

launchImage
For iOS, use for identifying the image used as the launch image.
For Android, use for identifying large icon for showing in the ticker.

fireDate
The date and time when the system should deliver the notification. The default timezone is used. If the specified value is null or is a date in the past, the notification is delivered immediately.

repeatInterval
The calendar interval at which to reschedule the notification. The intervals can be:

  • Notifications.CalendarUnit.ERA (iOS only)
  • Notifications.CalendarUnit.YEAR (iOS only)
  • Notifications.CalendarUnit.DAY
  • Notifications.CalendarUnit.HOUR
  • Notifications.CalendarUnit.MINUTE
  • Notifications.CalendarUnit.SECOND
  • Notifications.CalendarUnit.WEEKDAY (iOS only)
  • Notifications.CalendarUnit.WEEKDAYORDINAL (iOS only)

iOS Only Features

applicationIconBadgeNumber
The icon badge number of the application. The default value is 0 and it equals no badge is displayed.

hasAction
The boolean value that is used for showing or hiding the alert action. Setting it false hides the alert button or slider. To change this, alertBody should not be null.

userInfo
An optional key-value content. Your app can retrieve this later on if it receives the notification after the notification fires.

Android Only Features

smallIcon
It uses for notification layouts. Its sizes changes in different devices.

alertTitle
Title of the notification.

autoCancel
Setting this flag will make the notification is automatically canceled when the user clicks it in the panel.

number
Sets the large number at the right-hand side of the notification.

when
Sets the time that the event occurred.

usesChronometer
Shows field as a stopwatch. It needs API 16 or above.

vibrate
Sets the vibration pattern.

ticker
The text that is displayed in the status bar when the notification first arrives.

subText
Set the third line of text in the platform notification template. It needs API 16 or above.

priority
Sets the relative priority for this notification. It needs API 16 or above. It can be:

  • Notifications.NotificationProirity.DEFAULT
  • Notifications.NotificationProirity.HIGH
  • Notifications.NotificationProirity.LOW
  • Notifications.NotificationProirity.MAX
  • Notifications.NotificationProirity.MIN

actions
Sets the actions to the notification. It needs API 16 or above. This parameter is an array of JavaScript objects with the properties below:

  • title : Describes the action.
  • icon : Represents the action.
  • action : When the action is invoked, this event fired.

progress
Sets the progress this notification represents, which may be represented as a progressbar. This parameter is a JavaScript object with the properties below:

  • max : Max value of the progressbar.
  • progress : The increment value of progress.
  • indetermine : If you want the progress indetermined, you must set this parameter to true.
  • updateTimeMillis : The time progress in milliseconds that updates itself.
  • closePostProgress : Using close progressbar from notification or not after finishing.
  • iconPostProgress : For showing small icon after progress is done.
  • bodyPostProgress : For showing body text after progress is done.

bigText
This string parameter enables large-format notifications that include a lot of texts.

bigPicture
This parameter enables large-format notifications that include large image attachments.

id
This is the key for the notification.

Methods & Events

LocalNotification()

Creates local notification object.

var localNotification = new Notifications.LocalNotification({
		id : 1,
		fireDate : new Date(),
		alertTitle : "AlertTitle",
		alertBody : "Alert Body",
		smallIcon : "icon_notification_small.png",
		launchImage : "icon_notification.png",
		sound : "notifsound.mp3",
		repeatInterval : Notifications.CalendarUnit.MINUTE,
		onReceivedNotification : function (e) {
			alert("onReceived");
		}
	});

Notifications.local.scheduleNotification()

Schedules a local notification for delivery at its encapsulated date and time. It takes a local notification object that has specified fireDate property.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		id : 1,
		alertTitle : "AlertTitle",
		smallIcon : "icon_notification_small.png"
	});
Notifications.local.scheduleNotification(localNotification);

Notifications.local.presentNotification()

Presents a local notification immediately regardless of value of the notification’s fireDate property.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		id : 1,
		alertTitle : "AlertTitle",
		smallIcon : "icon_notification_small.png"
	});
Notifications.local.presentNotification(localNotification);

Notifications.local.cancelNotification()

Cancels the delivery of the specified scheduled local notification. For iOS it compares all existing notifications using userInfo property.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		userInfo : {
			"key" : "value"
		} // FOR iOS
	});
Notifications.local.presentNotification(localNotification);

For Android, it compares all notifications using alertTitle, alertBody, id and smallIcon properties.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertTitle : "Alert Title", // FOR ANDROID
		alertBody : "Alert Body", // FOR ANDROID
		id : id, // FOR ANDROID
		smallIcon : "icon_notification_small.png" // FOR ANDROID
	});

Notifications.local.notify()

Uses Android only. Post a notification to be shown in the status bar. Using for replace updated notification’s information to old one.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		alertTitle : "My title",
		id : 1,
		smallIcon : "icon_notification_small.png"
	});
Notifications.local.presentNotification(localNotification);

Notifications.local.notify(localNotification);

Notifications.local.scheduledNotifications()

Returns all currently scheduled local notifications as an array type.

var notf1 = new Notifications.LocalNotification({
		fireDate : new Date(),
		alertBody : "Alert Body",
		repeatInterval : Notifications.CalendarUnit.day,
		id : 0,
		alertTitle : "AlertTitle",
		smallIcon : "icon_notification_small.png"
	});
var notf2 = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2014 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		id : 1,
		alertTitle : "AlertTitle",
		smallIcon : "icon_notification_small.png"
	});
Notifications.local.scheduleNotification(notf1);
Notifications.local.scheduleNotification(notf2);

var scheduletNotfs = Notifications.local.scheduledNotifications;

Notifications.local.applicationIconBadgeNumber()

For iOS only. Sets badge of the app icon. The default value of this property is 0.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2015 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body"
	});
localNotification.applicationIconBadgeNumber = Application.applicationIconBadgeNumber + 1;
Notifications.local.scheduleNotification(localNotification);

onReceivedNotification()

This function is Global Event. When a local or remote notification is invoked, function triggered.

var localNotification = new Notifications.LocalNotification({
		fireDate : new Date("Mon Dec 21 2015 19:50:41 GMT+0000 (EEST)"),
		alertBody : "Alert Body",
		id : 1,
		alertTitle : "AlertTitle",
		smallIcon : "icon_notification_small.png",
		onReceivedNotification : function (e) {
			alert("onReceived");
		}

onReceivedNotification – properties of “e”:

type

  • “Notifications.NotificationType.LOCAL”
  • “Notifications.NotificationType.REMOTE”

Properties of a LocalNotification
Ex: “e.fireDate” or “e.alertBody

Technical Considerations

Local notifications are generally fit for apps with time-based behaviors, like calendars. Apps that run in the background for the limited period allowed by iOS might also find local notifications useful.

It is recommended to specify the date and time of fireDate, because the operating system is delivering the notification, not the app itself. You can request the operating system to reschedule the notification at a regular interval (weekly, monthly, and so on).

In iOS, each app on a device is limited to 64 scheduled local notifications. The system discards scheduled notifications in excess of this limit, keeping only the 64 notifications that will fire the soonest.

If you want to use “notifyNotification()” feature, for Android, there is a special setting that End-User has to make in order to update to work, otherwise update will have no effect. This setting is called Notification Access.

When one of your scheduled local notifications triggers, these actions happens:

  • Your app is active:
    No change, the user won’t be informed by the system that the notification has fired; if there is a sound, no playing.
  • Your app is suspended in the background:
    If the user calls your app from a notification, your app is brought to the front.
  • Your app isn’t running:
    If the user summons your app from a notification, your app is launched.

If your app wasn’t active and the user summons it from a notification, you may want to show the user, immediately, some interface appropriate to this local notification. However, as your app appears, the user will first see either your default launch image (if the app is launched from scratch) or the screenshot image taken by the system when your app was suspended (if the app is activated from the background). To prevent a mismatch between that image and what the user will see when your app’s interface actually appears, you can include in the LocalNotification “launchImage” that more closely matches your app’s interface.

 

Under some special conditions your app might be running, not suspended, in the background. In this case, the situation is similar to what happens when your app is suspended: the user may be notified, and can bring your app to the front. Your running-in-the-background app can even schedule a notification to fire immediately with the convenience method: Notifications.local.presentNotification()