Push Notifications for Android and Apple Devices

Push notifications allow you to send messages and alerts to Android and Apple devices from external apps or processes which are separate from your Digitise apps. These notifications work in a similar way to notifications for other mobile apps, such as from games, messaging and social media apps, which most users will already be very familiar with. Each push notification is targeted at a specific Digitise app and can include data to be passed to the app within it. Notifications can be received whether the target app is running or not.

For example, suppose you have a Digitise app which provides a list of jobs for the user to work through and update on their mobile device and that this job list is stored in a central database and downloaded to the device at the start of each day. You could then have an app or process, separate from your Digitise Apps environment, which would notify users if the database is updated and the job list changes during the day, by sending a push notification to interested users. This app or process could be the same app or process which updates the database or it could be a separate app or process. The notification could contain the new data or initiate an automatic download of the updated database if required or the app can provide a mechanism for the user to update the data manually.

Push notifications are supported in both apps which are run from within a standard Digitise Apps Client and those deployed as Standalone Apps, but are only supported for the Android and Apple Platforms.

On the device, when a push notification is received, it will, generally, appear in the device's notification area in the standard manner for the device, although on iOS devices if the app is already running in the foreground, the app will display the notification rather than the notification centre. The user can tap or click on the notification to acknowledge the notification, which will bring the target app into the foreground - if necessary the app or Digitise Apps Client/target app will be loaded first, if not already running.

Once the target app is in the foreground, the OnSystemNotification Event will be triggered, just as with system notifications, and, if a Script has been assigned to the Event, that Script will run, allowing you to automatically perform a set of actions without user intervention, for example to automatically redownload an updated Data Source or handle any data included within the notification. The push notification must include a 'tag' value which will be passed to the OnSystemNotification Event to identify the notification's source (see below for more information) allowing you to use the OnSystemNotification Event for notifications from different sources. There is only one OnSystemNotification Event which is shared between all notifications - both push and system. This means that you can only assign one Script to the Event, which therefore has to cover the required actions for all notifications the app might receive. The supplied tag value is automatically stored in a predefined variable, Tag, and is used to identify the notification. The Tag variable can be accessed throughout your Script, and thus can be used to isolate those parts of the Script which relate to individual notifications.

The OnSystemNotification Event is an application-level Event, which can be accessed in App Studio from the Project Properties.

If the app named in the notification is a secondary app, i.e. it is launched from within another app, when the notification is acknowledged the secondary app will only be brought to the foreground if it is already running. If it is not running, the main primary app will be loaded or brought to the foreground instead and the OnSystemNotification Event in this app will be triggered.

Android Devices

Support for push notifications can be included within a pre-configured Digitise Apps Client and in Standalone Apps but isn't included within the default Android Digitise Apps Client supplied with the Install.

Push notification support requires a Google Firebase services file, which you can obtain from the Google Firebase web site and requires a gmail account. You will need to sign into the Firebase web site and download a file called google-services.json from the Firebase console. This file will be linked to a particular Digitise Apps Project or Digitise Apps Client and is used to add support for push notifications when you request a build of the linked app or Client within App Studio. Each Standalone App that you want to allow push notifications will need its own version of this file and, if you want to build a pre-configured Digitise Apps Client with push notifications, you will need another version of this same file for your Clients. (If you create multiple pre-configured Digitise Apps Clients, each one can use the same google-services.json file, you don't need to download a separate one for each Client.) Apps which will only be run from within a pre-configured Client and won't be turned into Standalone Apps, don't need a services file; only the Digitise Apps Client will need one.

When you request a version of the google-services.json file in the Firebase console, you need to supply something called a Package Name and it is this which links the file to your app or Client. You will need a different version of the file for each unique Package Name. You can find the Package Name you need for an app or Client under the General tab within the Build request dialog box in App Studio.

For a basic guide to obtaining a google-services.json file, see Add Google Firebase to an Android Digitise app. Note this file is also used to include Google Firebase Crashlytics crash and data usage reporting within an Android version of a Standalone App or pre-configured Digitise Apps Client.

Once you have downloaded the google-services.json file for an app or pre-configured Client, you can then build the app or Client and include push notifications in the build. To do this, you need to request a build of the Standalone App or pre-configured Digitise Apps Client in the usual way, but you will need to enable Firebase support and import the google-services.json file as part of configuring the build request.

To enable Firebase support:

Select the Enable Firebase option under the Build request dialog's General tab.

Click OK to dismiss the message informing you that you need to supply the google-services.json file, if it appears.

Choose the google-services.json button to the right of the option.

Click Browse File... to locate the google-services.json file you downloaded for this app or Digitise Apps Client.

Double-click on the file or select it and click Open.

The contents of the file will be displayed.

Click OK to return to the Build request dialog.

You can now configure the rest of the build request options as normal.

Users can configure and turn off support for notifications within the device's Settings. Note that if push notifications are disabled, the notifications are still sent but are ignored by the Client or Standalone App.

Push notifications for Android devices are processed and sent out by Google's Firebase Cloud Messaging (FCM) service. When you want to send out a notification, the app or process responsible for notifying users forwards the relevant information to the FCM service which then pushes out a notification to the device(s) specified within the request. Note that Digitise Apps doesn't support Channels for push notification distribution.

The actual sending out of a push notification can be achieved using the standard mechanisms for initiating push notifications - see Google's Android developer web site for more information. A utility which allows you to send push notifications manually, e.g. to simplify testing your Digitise apps, is also available from the NDL Helpdesk.

The body of a notification request must include what is called the payload. The payload consists of a set of data items and is sent to the device in the notification. The data items specify which Digitise app the notification is intended for, identifies the notification to the OnSystemNotification Event Script and may also include data which can be accessed and processed within the OnSystemNotification Event Script.

The payload is supplied as a JSON dictionary in the following format:

{

"appName":"<The name of the Digitise app>",

"tag":"<A name of your choice to identify the notification source to OnSystemNotification>",

"customData":"<data to be sent to the app>"

}

"appName":"<The name of the Digitise app>", - the name of the Digitise app this notification is intended for.

"tag":"<A name of your choice to identify the notification source to OnSystemNotification>", - this line provides a name which will be passed to the OnSystemNotification Event, within your app, triggered when the user acknowledges the notification and will be available within the Script's Tag variable. You can use this name to identify the code, within the OnSystemNotification Event Script, that you want to run when this notification is acknowledged on the device.

"customData":"<data to be sent to the app>" - custom data allows you to include data within the notification to be passed to the app, which will be accessible in the OnSystemNotification Event Script. This data can be targeted at individual users or generic data for all, or any, users. For example, you could notify users when new jobs are added to their job list and include details of the new job within the custom data. In this case, you might send the notification to all your users because they all view the same list or to an individual user because each user sees only jobs assigned to them. You can include as much data as you like here providing the total size of the payload doesn't exceed 4096 bytes (4K).

You can also split the data supplied into multiple parts, if you want to, e.g. where you want to send different bits of information which can be read separately within your OnSystemNotification Script. Data you want to include here must be contained in one or more key/value pairs in the format:

"<keyname>":"<value>",

...

You can choose any name for each key name, you don't have to call it customData. The <value> following the ':' contains the data associated with this key. The last line doesn't need a comma at the end.

The key name is used to extract the data associated with it in your OnSystemNotification Script.

Custom data is optional and can be omitted if not required.

iOS Devices

Support for push notifications within a Digitise app requires a Provisioning Profile which includes push notification capability. For new apps or pre-configured Digitise Apps Clients, you will need to obtain an appropriate Provisioning Profile before you can request a build of the app or Client. If you are updating an existing app, created with a version of MX, the predecessor to Digitise Apps, prior to MX - 2020 Vision Edition, and you want to add push notifications to it, you will need to obtain a new Provisioning Profile with push notifications enabled, rebuild your app and redeploy it to your users. You need a separate Provisioning Profile for each Digitise Apps Standalone App or pre-configured Digitise Apps Client and you cannot use a wildcard Profile when using push notifications. This is because the notification service has to be able to identify the exact app to direct the message to.

For information about obtaining a Provisioning Profile with push notifications capabilities see Obtain a Provisioning Profile with Push Notification Capabilities. Note that the Bundle ID can now be found displayed in the Build request dialog box in App Studio - in the Package Name field under the General tab.

You will need to upload an appropriate Provisioning Profile to the Digitise Apps Build System in the usual way, before you can build a Standalone App or pre-configured Digitise Apps Client including push notification capabilities.

Once you have uploaded a suitable Provisioning Profile for an app or pre-configured Client, you can then build the app or Client and include push notifications in the build. To do this, request a build of the Standalone App or pre-configured Client in the usual way, but you will need to enable support for push notifications by setting Enable Push Notifications, under the Settings tab in the Build request dialog box, to Yes.

If you include push notification support, users may be asked to grant permission to the app or Client to receive notifications, the first time they run the app or Client on a device. Users can subsequently configure and enable/disable notifications on a per-app basis within the device's Settings. Note that, if a user disables notifications, the notifications are still sent but are ignored by the Client or Standalone App.

Push notifications are processed and sent out by the Apple Push Notification service (APNs), which requires an Apple Developer account in order to access the service. When you want to send out a notification, the app or process responsible for notifying users forwards the relevant information to the APNs which then pushes out a notification to the device specified within the request. This can be achieved using the standard mechanisms for initiating push notifications - see Apple's Developer Program web site for more information. A utility which allows you to send push notifications manually, e.g. to simplify testing your Digitise apps, is also available from the NDL Helpdesk.

The body of the notification request must include what is called the payload. The payload consists of a set of data items and is sent to the device in the notification. The data items tell the device how to handle the notification, specifies which app the notification is intended for, identifies the notification to the OnSystemNotification Event Script and may also include data which can be accessed and processed within the OnSystemNotification Event Script.

The payload is supplied as a JSON dictionary in the following format:

{

"aps": {

"alert":"<The message you want to appear on the notification>",

"sound":"default",

"appName":"<The name of the Digitise app>",

"tag":"<A name of your choice to identify the notification source to OnSystemNotification>",

"customData":"<data to be sent to the app>"

}

"alert":"<The message you want to appear on the notification>", - this line must start with "alert"; background notifications are not supported.

"sound":"default", - enter this line as it appears here. This will use the sound settings specified on the device within the device's Settings.

"appName":"<The name of the Digitise app>", - the name of the Digitise app this notification is intended for.

"<key name>":"<value>",

...

The key name is used to extract the data associated with it in your OnSystemNotification Script.

Custom data is optional and can be omitted if not required.

If you include support for push notifications, every time you load the Standalone App or Digitise Apps Client it will automatically attempt to contact the relevant push notification service and register itself with the service. The service returns a unique identifier, called a push token, which identifies the device and Digitise Apps Client combination. When the app or process responsible for initiating push notifications requests a push notification, it will need to provide the relevant push token value in the request. This tells the push notification service which device and Digitise Apps Client it should send the notification to.

Consequently, a user should have a connection available the first time they load a new Digitise app or Client, otherwise they won't be able to register with the push notification service and won't receive push notifications. In this situation, you could tell your users to close and reload the app or Client when they have a signal again, or you could provide a Script within your app which will attempt to register with the notification service, using the RegisterForPush Scripting Method, and then, for example, assign that Script to a Button allowing the user to manually register or to a Timer for automatic retries, disabling the Timer once the device has registered.

Once the Client has registered with the notification service, it will still re-register whenever the app or Client is loaded. In general, the push token returned should remain the same each time a particular client registers, but this is not guaranteed. This means that if a device has no signal when the Client or app loads, it should still be able to receive push notifications using the same push token as before once it has a signal, even though it has been unable to reach the notification service on loading.

The push token identifies a Digitise Apps Client running on a specific device, rather than a Digitise app. Consequently, when requesting a notification, you include the name of the app the notification is intended for within the request, so that the Digitise Apps Client can deal with the notification correctly. (Remember a Standalone App includes a version of the Digitise Apps Client bundled within the app. The push token identifies the device and Digitise Apps Client and the notification payload then includes the name of the app.)

You must make sure that devices are not prevented from contacting the relevant push notification service due to firewall restrictions.

Since it isn't Digitise Apps which will send out the push notifications themselves, your Standalone Apps or Digitise Apps Clients need to be able to share their push tokens with the apps or processes which will actually send out the notifications, so that they can send notifications to the appropriate devices. One solution is to create a database to store the values in and upload the push token values from your Digitise apps to this database. The database will need to be accessible to the apps or processes which send out the notifications. The GetPushToken Scripting Method allows you to obtain the push token value within a Script and could be called from the Project's OnLoad Event.