Local Notifications

Local Notifications
Let your users know when something relevant to your app has happened

This tutorial requires you to be running LiveCode 5.5.

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.

Attached Files

LocalNotifications.livecode

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.