Push Notifications

When the mobile app starts, it connects to the Firebase servers and obtains a Push Notification token (fcm token). The app generates a unique DeviceID hash based on the mobile device ID and the company that created the app (iOS) or the app (Android). The DeviceID will change if the app is re-installed.
When a user logs into the district portal using their conuniq or StudentID, assuming that the user allows mobile push notifications, the portal StudentConnection/ParentConnection) will attempt to write the fcm token into the
Mobile_UserTokens table.
In an effort to protect the privacy of the user, the DeviceID is used to limit the number of users registering to receive notifications on the same device to one. It is assumed that the first user who logs in from any given device is the owner of the device and should be the only one to receive push notifications on that device.
If a user has multiple devices, they can receive push notifications on any or all of the devices.
If the wrong user accidentally gets associated with a device, the owner of the device should uninstall the application (thereby resetting the DeviceID) and then open the app and log in.
Once created in Mass Email, a Windows Service continually polls the database and sends out the notifications created in Q.
 You must install the Push Service, and then configure the connection files used by the service.

• Used to poll database for Push Notifications that need to be sent
• Queries database every 10 seconds with sql procedure qPushService_PollQueue
• Uses the following database tables:
  • Mobile_UserTokens
  • Mobile_PushMessage
  • Mobile_PushMessageRecipient
• When there are messages to send, the service creates an http connection to the Firebase
   servers (https://fcm.googleapis.com/fcm/send) and sends each message as a json object
• The status of each message sent is stored  n Mobile_PushMessageRecipient.Status
  The possible status codes are:
  • -1 : Pending – not yet picked up by windows service
  • -2 : In Process – picked up by windows service and is queued or in the process of being
     sent
  • 200: received by Firebase
  • Other positive status codes: Error reported by Firebase, more details in the
     PushStatusMessage
  • -99: Token not registered (invalid)
• The field Mobile_PushMessageRecipient.StatusMessage may contain an error message in the event of an error while sending the message (e.g. time out, invalid token, …)

The service is in the QMobile_PushService.zip file delivered in this version. Unzip this file to a folder where you will run the service from.
The windows service used by the push notification server can be installed with the Microsoft InstallUtil.exe utility.
 It can be found in the following folder:

C:\Windows\Microsoft.NET\Framework64\v4.0.30319

Note: It is recommended that when installing the service, it be configured to restart on failure.
From a windows command prompt, change to the directory folder listed above.
From the prompt, type in the following command:
 InstallUtil [path of exe]

[path of exe] is the complete path to the windows service exe delivered with Q.

Example: InstallUtil c:\QMobile_PushService\QMobile_PushService.exe
 Once the install is successful, 2 files will be created in the folder where the exe resides:

• QMobile_PushService_WinService .InstallLog
• QMobile_PushService_WinService .InstallState

To uninstall the service you just add the /u switch.
 Example: InstallUtil /u c:\QMobile_PushService\QMobile_PushService_WinService.exe

Configure Connections in App_Data Folder

The Push Notification Server uses the same type of connection files as those used in Q for connecting to a database. This folder contains all the connection files for use by the server. These files are identical to the connection files used by Q.
Start by copying only the necessary and valid connection files from your Q\App_Data folder into the QMobile_PushService\App_Data folder for the Push Service. The Push Service will attempt to use every
connection file. Any connection file that is invalid will not stop the service from working, but the service will attempt to reconnect to any database that it cannot access every 5 minutes.
It is possible to set up connection files for the Push Service to send push message from any database.
The AEConnect utility is delivered in the App_Data folder and can be used exactly as it is in Q to create the connection files.

Start Service

If you have completed all the above configuration successfully, you may now start the windows service.
Run the Windows Services application, and locate the Q Mobile Push Notifications Service.
Start the service. Once you have it installed and working, set the startup mode to Automatic.
The Q Mobile Push Notifications should now be operational.

• Mass Email has been enhanced to allow creation of Push Notifications
• There is a new sub-right to give users rights to send Push Notifications
• The application defaults to sending Email. If the user has the new sub-right, and the user has
  access to students who either have a push notification token in the Mobile_UserTokens table,
  or one of their contacts has a push notification token, the user will see a drop down in the app
  button bar to be able to send “Mobile Notifications”
  • Use of this app for Push Notifications is very similar to Mass email:
  • Compose the push notification
  • Select students
  • Click the Retrieve Students button
  • Sorting is alphabetical by students who have notification tokens or who have contacts
     who have notification tokens, then alpha for all other students
  • Rest is the same as Mass Email
• The Push Notification titles are limited (by Aequitas) to 50 characters and the body is limited (by
  Aequitas) to 1800 characters. Even though we set that limit, we highly recommend making push
   messages significantly shorter as long messages are difficult to read on a phone.

• Some districts may choose to create push notifications through a QLIP or thru a daily job (be
   aware that you are sending notifications to people!)
• Notifications can be created for students and contacts who have a non-retired record in the
  Mobile_UserTokens table
• Messages are created by inserting a record into the Mobile_PushMessage table for the message
   to be sent
• Insert a record into the Mobile_PushMessageRecipient table for each recipient
   Note: There can be multiple recipient records created for a single message
• The Mobile_PushMessage.senderfuniq is the funiq of the sender responsible for the
   message. You can set this to null for automated jobs or hooks or set it as appropriate
• The Mobile_PushMessageRecipient.PushMessageID is a reference to
  Mobile_PushMessage.PushMessageID to tie what message to send to the recipient
• The Mobile_PushMessageRecipient.PushSubscriptionID is a reference to
  Mobile_UserTokens.ID to indicate the recipient token to use
• The Mobile_PushMessageRecipient.PushSubscriptionID.suniq field is used by Mass Email to
   perform variable substitution and is not required (can be set to null)
• The Mobile_PushMessageRecipient.PushMessageRecipientID field is an identity field. Do not
   include it in any insert statement you may create
• Set the Mobile_PushMessageRecipient.Status field to -1
• Set the Mobile_PushMessageRecipient.StatusMessage to NULL
• Sample Code for sending to all the devices of a contact:

declare @conuniq int, @senderfuniq int, @now datetime, @PushMessageID int, @title varchar(50),
@body varchar(1800), @PushSubscriptionID int

set @conuniq=1707
set @senderfuniq=1
set @title='Title of my message'
set @body = 'Body of my message'
set @now = getdate()

insert into Mobile_PushMessage (senderfuniq, title, body, createdatetime)
select @senderfuniq, @title, @body, @now

select @PushMessageID=PushMessageID
from Mobile_PushMessage
where senderfuniq=@senderfuniq and title=@title and body=@body and createdatetime=@now

if @PushMessageID is not null
insert into Mobile_PushMessageRecipient (PushMessageID, PushSubscriptionID, suniq, SendDatetime,
PushStatus, PushStatusMessage)
select @PushMessageID, t.ID, null, null, -1, null
from Mobile_UserTokens t
 where t.atype='C' and t.auniq=@conuniq and t.isRetired=0