Using local notifications
Local notifications allow applications to communicate with the user, whether they are running in the foreground, the background or not running at all. The app schedules notifications with the operating system to be delivered to the used at a certain time.
The way in which the notification is delivered depends on the mode in which the application is in at the time the notification is received. If the application is running when the notification is received it can handle the display of the notification as required. If the app is not running then the user is notfied and can choose what action to take, for example the use can choose to dismiss the notification or launch the app.
Our sample stack
In this lesson we will use a sample stack to create, send and cancel local notifications. The stack consists of 2 buttons, for sending and cancelling notifications, 3 fields to specify the contents of the notification and button label, a picker to specify when the notification shouel be sent and a checkbox to specify if the device should make a sound/vibrate when a notification is received.
Creating a local notification
You create a local notification using the mobileCreateLocalNotification command. This command takes up to 6 parameters
alertBody - The text that is to be displayed on the notification dialog that is raised when the application is not running.
alertButtonMessage - The button text on the notification dialog that is to appear on the button that launches the application, when the application is not running.
alertPayload - A text payload that can be sent with the notification request. This payload is presented to the user via the localNotificationReceived message.
alertTime - The time at which the alert is to be sent to the application. This parameter needs to be set in seconds and is the number of seconds since the UNIX Epoch, at which the notification should be triggered.
playSound - A boolean to indicate if a sound is to be played when the alert is received.
badgeValue - The number value to which the badge of the application logo is to be set. 0 hides the badge. >0 displays the value on the badge (optional)
The script of the "Send" button is
on mouseUp
local tCurrentTime, tNotificationTime, tAlertBody, tAlertButton, tAlertMessage, tSound
put the seconds into tCurrentTime
put field "alertbody" into tAlertBody
put field "alertbutton" into tAlertButton
put field "message" into tAlertMessage
put tCurrentTime + word 1 of field "seconds" into tNotificationTime
put the hilite of button "sound" into tSound
mobileCreateLocalNotification tAlertBody, tAlertButton, tAlertMessage, tNotificationTime, tSound
end mouseUp
Cancelling notifications
You can cancel pending notifications using the mobileCancelAllLocalNotifications command. This command cancel all scheduled local notifications.
The script of the "Cancel Pending Notifications" button is
on mouseUp
mobileCancelAllLocalNotifications
end mouseUp
Handling notifications when the app is running
If your app is running when a local notification is sent it receives a localNotificationReceived message, this message is sent with a message parameter. This message is the alertPayload that was specified when the notification was created.
We handle the localNotificationReceived message in the card script of the stack
on localNotificationReceived tMessage
answer "Local Notification:" && quote & tMessage & quote with "Okay"
end localNotificationReceived
Handling notifications when the app is not running
If your app is not running when a local notification is received the user is alerted and can choose what action to take.
On iOS a dialog box can be launched or the login screen can be opened to inform the user that an application has information for them. Android can create an application icon in the status bar. The user can then decide whether or not to open the application.
If the application is opened as a result of the notification, then LiveCode can handle the localNotificationReceived message as above.
Add your comment