Mobile Notifications

Notifications

Both the Android and iOS operating systems support notifications, which are ways of sending messages to your app through the device's OS. There are two types of notifications—local and push.

Local notifications — The app schedules a notification with the operating system. The notification is sent back to the app after the specified amount of time.

Syntax:

mobileCreateLocalNotification alertBody, alertButtonMessage, alertPayload, alertTime, playSound [, badgeValue]

Where:

alertBody is the text to be displayed in the alert dialog that appears if the notification occurs when the application that produced it is not running.

alertButtonMessage is the label of the button in the alert dialog that appears if the application is not running. Clicking on this button will launch the application that originated the notification.

alertPayload is a text string that can be sent to the user with the notification. If the app that originated the notification has a localNotificationReceived message handler, this text string can be presented to the user.

alertTime is the time at which the notification should be triggered. This time is given in seconds since the beginning of the Unix epoch, 1 Jan 1970 12:00:00 midnight.

playSound is true or false, indicating whether an alert sound should be played when the alert is received.

badgeValue is a number value to which the badge on the application icon is to be set. (This is an iOS-only feature.)

Example:

local sNotificationID
. . . 
mobileCreateLocalNotification "Notification Alert Text", "Go", "Text string sent to the app.", the seconds + 10, true, "1"
put the result into sNotificationID

In this example the result function is used to retrieve and store an id number for the local notification. This is useful because you can cancel a specific notification if you know its ID number:

mobileCancelLocalNotification sNotificationID

To cancel all pending notifications use:

mobileCancelAllLocalNotifications

Once a notification has been scheduled, the following things happen, depending on what app the user is running when the notification time arrives:

If you have left the app that originated the notification, a notification alert appears on your device's screen. The text in the alert is the alert body from above, with a button labeled with the alertButtonMessage from above.
When you respond to the alert and go to the app that sent the local notification, a localNotificationRecieved message will be sent to the first card of your app. Your app must handle this message if you want to do something with the notification:

Syntax:
```
localNotificationReceived alertPayloadString
```
Where:

alertPayloadString is the alertPayload sent with the mobileCreateLocalNotification command.
If you are in the app that sent the notification AND the localNotificationRecieved message is handled, whatever you programmed into that handler will be executed.

The last argument in the mobileCreateLocalNotification command is badgeValue. This is an iOS-only* feature that adds a number inside a red circle to your app's application icon, giving a visual signal that an app has a notification pending, as with the Reminders app in the screen shot below.

iOS notification badge

* UPDATE 4/2020: Although this feature is marked as "iOS only" in the LiveCode dictionary, it appears that it in fact does work on Android devices, as tested with LiveCode 9.5.1 and Android v. 9.

To turn off the notification badge use the iphoneSetNotificationBadgeValue command. This command is iOS-only, and you have to explicitly reset badges on iOS. On Android devices the badge is cleared automatically when you return to the app that generated the notification.

Syntax:

iphoneSetNotificationBadgeValue number

Where number is the numeral you want to appear on the badge.

Example. Here we are turning off the badge by setting the number to 0:

on localNotificationReceived pMessage
   answer "Local Notification:" && quote & pMessage & quote with "Okay"
   iphoneSetNotificationBadgeValue 0
end localNotificationReceived

See this lesson online for complete instructions on using local notifications:

http://lessons.livecode.com/s/lessons/m/4069/l/58669-using-local-notifications

Push notifications — Whereas a local notification comes from the local device, a push notification is one that is sent to the device from a Push Notification Server. This service makes it possible to notify the device of the availability of new remote data for an app, and allows the app to avoid repeatedly polling a server for the availability of new remote data.

The process of setting this up is much more involved than local notifications, due to security considerations. Here is a lesson that explains it in detail:

http://lessons.livecode.com/s/lessons/m/4069/l/53405-how-do-i-use-push-notifications-with-ios

Back BYU LiveCode Lessons Gateway