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:
The message displayed in the notification.
This matters only if your notification is displayed as an alert; in that case, this is the text of the action button.
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.
For iOS, use for identifying the image used as the launch image.
For Android, use for identifying large icon for showing in the ticker.
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.
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.WEEKDAY (iOS only)
- Notifications.CalendarUnit.WEEKDAYORDINAL (iOS only)
iOS Only Features
The icon badge number of the application. The default value is 0 and it equals no badge is displayed.
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.
An optional key-value content. Your app can retrieve this later on if it receives the notification after the notification fires.
Android Only Features
It uses for notification layouts. Its sizes changes in different devices.
Title of the notification.
Setting this flag will make the notification is automatically canceled when the user clicks it in the panel.
Sets the large number at the right-hand side of the notification.
Sets the time that the event occurred.
Shows field as a stopwatch. It needs API 16 or above.
Sets the vibration pattern.
The text that is displayed in the status bar when the notification first arrives.
Set the third line of text in the platform notification template. It needs API 16 or above.
Sets the relative priority for this notification. It needs API 16 or above. It can be:
- title : Describes the action.
- icon : Represents the action.
- action : When the action is invoked, this event fired.
- 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.
This string parameter enables large-format notifications that include a lot of texts.
This parameter enables large-format notifications that include large image attachments.
This is the key for the notification.
Methods & Events
Creates local notification object.
Schedules a local notification for delivery at its encapsulated date and time. It takes a local notification object that has specified fireDate property.
Presents a local notification immediately regardless of value of the notification’s fireDate property.
Cancels the delivery of the specified scheduled local notification. For iOS it compares all existing notifications using userInfo property.
For Android, it compares all notifications using alertTitle, alertBody, id and smallIcon properties.
Uses Android only. Post a notification to be shown in the status bar. Using for replace updated notification’s information to old one.
Returns all currently scheduled local notifications as an array type.
For iOS only. Sets badge of the app icon. The default value of this property is 0.
This function is Global Event. When a local or remote notification is invoked, function triggered.
onReceivedNotification – properties of “e”:
Properties of a LocalNotification
Ex: “e.fireDate” or “e.alertBody
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()