AddSystemNotification

AddSystemNotification(tag, message, actionortitle, when, sound, repeat, options)

Display a message on a specified date and time in the device's standard notification area, load a Digitise app and run a Script. You can specify a repeat and also play a sound when the notification occurs.

All

tag - required

String containing a name of your choice to identify this alert.

If you call this Method with a previously used tag specified, the previous alert/reminder for the tag will be replaced with the new one.

Note on the Windows Universal Platform the tag has a maximum length of 15 characters. Therefore, we recommend that you limit the length of your specified tag to 15 characters on all Platforms, to allow for cross-platform compatibility.

 

message - required

String containing the message you want to be displayed when the alert/reminder is actioned.

See Notes below for some additional information.

 

actionortitle - required

On the Android, Windows Desktop and Windows Universal Platforms enter a Title for the alert/reminder message displayed.

On iOS devices the string specified here will be displayed in the message as the label to a 'button' which the user taps to acknowledge the notification.

See Notes below for some additional information.

 

when - required

Date and time at which the first alert/reminder will occur. This should be in the following UK format:

25/07/2014 13:15:00

If the date is in the past, the notification will display immediately and then, if a repeat interval is specified in the repeat parameter below, at the specified repeat interval from the original date specified here, not from the date the first notification displays.

You can use the Now Scripting Method to obtain the current date and time in the correct format, otherwise, if entering an actual date, the value should be enclosed in quotes, e.g. "01/01/2022 01:01:00".

 

sound - required

Determines whether a sound should be played to alert the user to the message. Can have one of the following values:

 

repeat - required

Specifies a time period for repeating the alert/reminder. Can have one of the following values:

Note, that "MONTH" and "YEAR" values are only supported on the Apple, Windows Desktop and Windows Universal Platforms. If an invalid value is supplied on Android devices a Script error will be displayed.

 

options - required

String containing a comma separated list of Options which can be used to alter the behaviour of the notifications.

Can include any of the following values:

 

For example, on an Android device you might specify the following Option string:

"NO_ACTION, NO_CANCEL, NO_RETAIN_ON_REBOOT"

Note that if you specify an unsupported Option on a particular device, that Option will be ignored.

Failure.

Success.

AddSystemNotification allows you to generate local system notifications from within a Digitise app allowing you to provide alerts and reminders to users of the app. AddSystemNotification allows you to configure a system notification and register it with the device's operating system notification facility. The notification is registered locally on the user's device and only displays the notification message on the device on which it registered; it doesn't affect other users or devices.

For more details about system notification see: SystemNotifications.

• If a notification is acknowledged by the user, the Digitise app which registered the notification will, generally, be brought to the foreground and the OnSystemNotification Event is triggered. The notification's identifying tag, specified in the original Method call's tag parameter, is passed to the Event to identify the notification that triggered the Event. The tag is passed to the Event as a parameter and is placed into a pre-defined variable called Tag which is then accessible within your Script, allowing the one Script to deal with different notifications.

• The options parameter allows you to modify certain aspects of the alert's behaviour – see parameters section above for details.

• On the Android and Windows Desktop Platforms, if you leave both the message and actionortitle parameters blank then the notification will not be displayed but the Digitise app responsible will be brought to the foreground as usual and the OnSystemNotification Event will still be triggered.

  On iOS, if you leave both the message and actionortitle parameters blank and the Digitise Apps Client is not in the foreground, no notification will be displayed but a "Badge" number will be displayed over the app's icon on the device's Home screen. If the Client is in the foreground, the Client will bring the app into the foreground, if not already there, and display a message saying 'New Notification'. Tapping the OK button will dismiss the message and run the OnSystemNotification Event.

• On Android, Apple and Windows Desktop Platforms, you can specify a sound file to be played when the notification occurs. We recommend you use an mp3 or wav file. Other audio files may work but you will need to experiment with your particular device to determine which file types are suitable.

  The file must first be imported into your Project before it can be referred to here. The sound parameter can reference the file using its Resource ID or file name. The Resource ID is the name of the sound file as it appears in the app Studio's Resources Pane tree view, e.g. ID_SOUND_MYTUNE_1. You can find the Resource File Name by selecting the sound within the Resources Pane and then looking in the panel at the bottom of the pane.

  If no sound is heard when a notification is received, check that sound hasn't been disabled or turned off for notifications.

  On Apple devices you can only specify a sound file to play with Standalone Apps. The sound will not play if you run the app within the Digitise Apps Developer Client. The specified sound must be less than 30 seconds in length or the default sound will play instead. The name of the sound file is case-sensitive. In addition, you can choose whether the notification sound, if specified, should play if a notification is received when the app is in the foreground. This is done using the SetApplicationOption Scripting Method.

  Custom sound files are not supported on the Windows Universal Platform.

• You can cancel a pending notification using the RemoveSystemNotification Method. This Method requires the name specified in the tag parameter in the original AddSystemNotification call used to create the notification.

  Note that on the Windows Desktop Platform, closing the Digitise Apps Client automatically cancels any outstanding notifications registered from apps running within that Client session.

  If you forget the tag used for a particular notification, you can display it in a message from within the OnSystemNotification Event using the Tag variable to obtain the tag value, e.g. MsgBox(Tag).

• If you specify "NO_FOREGROUND_ALERT" in the options parameter, the "NOTIFICATION_PLAYSOUND_IN_FOREGROUND" option available in the SetApplicationOption Method will have no effect.