Push Notifications

Push notification is a feature available in the UMS App, however only when using 'My Education App'. This allows the schools teachers and students to receive notifications on their phone about things such as news, timetable changes , grades and receive SMS Alert as notifications.

Requirements

• The school must be using 'My Education App'
• iOS must be version 10 or greater
• Android must version be 26 or greater

Setup

Institution

Contact InLogic to have Hub name provided, along with generated server-keys endpoints.

Only 1 hub per UMS installation supported

Inlogic Support

Go to https://portal.azure.com/

Create a new hub under the "umsapp-inlogic" Notification Hub Namespace, with the name matching the institution of the customer.

After creating the hub for the institution, open the hub and copy the connection settings for "Apple (APNS)" and Google (FCM v1) from the other hubs. These settings are the same for all "My Education App"/"UMS App"s installations.

Then under the "Manage" section, select "Access Policies" to get the auto generated Endpoints.

Give the Hubname, DefaultListenSharedAccessSignature endpoint (listen permission) as well as the DefaultFullSharedAccessSignature endpoint (manage, listen and send permissions) to the customers(to be entered into their configurator).

Once the Customer has entered the lines in the right fields, saved and added the template, users will be able to login to the app(re login if they don't want to wait a day) to register for push notifications. Inlogic support can then use the Test Send function(highlighted in blue), to send a test message, more on that in the "Testing" section.

Institution

The hubname and the Endpoints have to be entered into the matching fields below in the configurator > edit template > app > Push notification.

Description can be whatever you wish to denote it as, but Hub name and the Endpoints have to match the correct information or the module won't work.

After this, press OK and ensure that all templates has this setting selected.

In the configurator, under Settings>Services, it is important that the field "App Service" has been filled in, as the app service is in charge of sending the notifications to the hub.

Testing

After the endpoints have been entered into the configurator, a user that has logged in will be prompted for whether they want to receive push messages, once a user has been chosen, test notifications can be sent from the Inlogic azure platform by inlogic og normal notifications can be sent from the web.

Before beginning testing please read the "Known issues" segment as some of these may come up.

Inlogic support

In "Platforms" select the desired platform, either Apple or Android(currently only supported services).

In "Send to Tag Expression" either enter an accepted tag to specify a target or leave empty to send to all 10 random registered devices.

Accepted tags are:

"CustomerId#broadcast" : Broadcasts to members of an institution with the specific customer id.

"CustomerId#user#username" : Sends to a specific user belonging to a specific customer id, which makes this the most useful option for testing.

"deviceID" : Sends to a specific device that is registered on the hub, impossible to know unless you have access to the database in the "AppTokens" table.

Payload is the structure of the message including data on how the device should show the notification.

Our default payloads for Android is:

{"notification":{},

"data":{"NewsId":Number,"Type":number,"Title":"Text","Message":"Text","Payload":json object}}

Where Title and message are used for the Title and body of the Notification when showing on the phone.

NewsId is used for news notifications to open a specific news item, if you write the wrong number it will give you an error when you tap it on the phone.

Type is the type of the notification, which decides how the app reacts when the notification is tapped. Currently supported types are: 1: News, 2: Timetable, 3: TimetableChanged, 4: Grades, 5: Alerts, and 0 Unknown type which unsupported types default to and will give you an error when tapped.

Payload is currently unused but open for extra data once we expand the use of push messages.

Our default payloads for Apple is:

{"aps":{"alert":{"title":"Text","body":"Text"},"sound":"iOS Setting"},

"data":{"NewsId":Number,"Type":Number,"Title":"Text","Message":"Text","Payload":Json object}}

Where everything in APS controls the design of the notification, Title and Body is the same as Title and Message in Android, while in iOS the data fields for text and and message of the same name aren't used, they need to be there to fit the data object. Sound is an iOS setting on what sound to play when the notification is received by the phone, which we usually set to "default".

The data part is the same for both Android and iOS, it is the object used to manage notifications in the app.

After sending

Once you have filled in the fields above, you can click send and the hub will tell you the result of devices that have been sent to or if the payload isn't in an accepted format.

This can be used to check if your registrations/deregistrations have been updated and also if the message sent is received and works as intended/expected on targeted phones.

Institutions

If you don't have access to your database, what you can do on your own is to send push messages to specific users or teams when creating news, though it excludes alerts, grades and timetable notifications.

Otherwise if you do have access to your database, you can manipulate the "AppPushNotificationQueue" table, which allows to you send it to specific users and different types of notifications.

Sending messages can take up to 5 minutes as that is the interval the app service runs on.

When to expect a push notification

The app service is set to run every 5 minutes, which means after you complete the following actions there may be a timelag of 5 minutes before the service contacts the hub to send messages.

1. Create a News item: If send push is marked this is immediately added to the push queue, this is the fastest one you can test with.
2. Make changes to timetable Items, requires you to run "GetSkemaBrikker" to completion, before a push notification is added to the queue.
3. Adding a grade requires you to run "GetGrades" to completion, before a push notification is added to the queue.

Add to this that issues on the azure hub may delay a push for whatever reason. The app service will keep trying to contact the hub until the hub receives the request to send a push, but the hub may be unable to send it instantly, We know of 1 situation where the push took just above one hour since the time the push was sent from the app service.

Known issues

For whatever reason some devices may have issues registering with the notification hub, so far we do not know what causes it, but suggest making sure the push settings for the institution are properly setup before jumping to conclusions as it may be fixable.

Rapidly registering and deregistering can cause issues with the notification hub on a device basis. As such we heavily suggest you don't do so. you can reset this by doing a reinstall of the app as that will be the most clear "deregistration" the app can do.

Azure hub may have push messages saved in buffer for a while before sending it out(sometimes hours), cause unknown.

Users do not currently have a way to know if they are properly registered with the hub in the app, we are contemplating a way to add feedback for this. -You only get response when doing a registration/de-registration action.

The app service may not be able to send on the currently released version as it has checks on the wrong licenses. Fixed in beta versions of the frontend and backend as at the time of writting(1. of april 2022) any version newer than the beta should not have this issue.

FAQ

Q: Which devices are supported?

A: Android 8+ and IOS.

Q: Why can't I receive push notifications?

A: If you made changes in the Configurator, you will either need to wait a day, or log out and back in, in the app, for the settings to pass through. Additionally ensure the phone has permitted push notifications.

Q: Can I use Push Notifications with the traditional app (not 'My Education App')?

A: As it stands right now, this is not something we support.

Q: Which OS are supported?

A: Currently only android(through google and iOS are supported.