Targeted notifications allow OneCampus to communicate with your institution’s notification system to retrieve and display messages to end users in an inbox style dropdown. One example of how this might be used is to display a user’s “action list” or other type of “inbox” data.
After a user logs in, they will be presented with a new “mail” badge next to the Global Announcement icon (bell). If you do not have Global Announcements turned on, then Targeted Notifications will appear next to the user dropdown.
The Targeted Notifications badge will incrementally list the number of notifications that the end-user has and then disappear once the end-user has read them.
When an end user logs into OneCampus from their mobile device, the targeted notifications new mail badge will appear directly above the search bar and to the left of the sign in drop down, next to the Global Announcement icon (bell).
Please note: OneCampus does not store or manage any targeted notifications. Rather, OneCampus relies on your notification system that has been configured to work with OneCampus as outlined in the instructions below.
Configure your OneCampus tenant for Targeted Notifications
In order to utilize the Targeted Notifications feature, you will need to configure 3 tenant settings.
- Click the Advanced menu > Settings > Notifications Enabled
- Notifications Enabled turns the feature on or off. When turned off, the mail icon will be hidden and the functionality associated with targeted notifications will be turned off. This setting is off by default.
- Click the Advanced menu > Settings > Notifications Api Key
- Notifications Api Key is a 128-bit key that OneCampus uses to secure the communications with your notification system.
- We use a static init vector of "RandomInitVector" in a UTF-8 spec as well as a cipher of "AES/CBC/PKCS5PADDING" in conjunction with the API key when we encode.
- Alternately, you can use the Generate Key button on this screen to generate a 128-bit API key for yourself if necessary.
- Notifications Api Key is a 128-bit key that OneCampus uses to secure the communications with your notification system.
- Click the Advanced menu > Settings > Notifications Endpoint Url
- Notifications Endpoint Url is the “https://” url of the notification system that OneCampus communicates with to retrieve notifications and mark the notifications as read after they are viewed.
Notification System Configuration
In order for OneCampus to be able to retrieve notifications from your notification system, the notification system needs to be configured to work with OneCampus. In each request that is made to the Notification system, an encoded user parameter is passed along with a UNIX timestamp, such as:
{NOTIFICATIONS-ENDPOINT-URL}?user=IyKwpDJhL0TwF3JPuXQzsf1n+gLsu4oVTJB/eAAb9l0=×tamp=1481913927051
The part before the question mark is the endpoint url you enter into the system (HTTPS is highly recommended otherwise the user might see warning messages). The rest is completely generated by the system.
The user parameter consists of “username|timestamp” (pipe in between) and is AES base64 encoded using the Notifications Api Key. The notification system should decode this parameter using the same API Key and compare the decrypted timestamp with the timestamp provided in the timestamp parameter as well as use the decrypted username to retrieve notifications for the specific user. This is a security measure to ensure that the request was not changed before being sent to the notification system. It will also prevent someone from trying to retrieve notifications that are not meant for them.
OneCampus expects the notification system send all active notifications when it responds to both the GET request as well as the POST. This is required in order for OneCampus be able to mark the notifications as read.
Retrieving Notifications
On each page load, OneCampus will send a GET request in the form of
{NOTIFICATIONS-ENDPOINT-URL}?user=IyKwpDJhL0TwF3JPuXQzsf1n+gLsu4oVTJB/eAAb9l0=×tamp=1481913927051
and is expecting the notification system to provide a JSON response in a format following this example:
{
"numNewNotifications": 33,
“notificationSystemLink” : “https://notifications.mycampus.edu”,
"notifications":[
{
"date":1458327195576,
"id": 0,
"message": "You owe money and may not be able to register!",
"newMessage": true,
"sender": "Bursar",
"subject": "Hello, jmartinez! Pay your bill.",
“link”: “https://www.busar.edu”,
“linkText” : “Pay here”
},
{
"date": 1465925123822,
"id": 1,
"message": "You must return your book or pay a fine!!",
"newMessage": true,
"sender": "Library",
"subject": "Hello, jmartinez! Your book is now overdue.",
“link”: null,
“linkText” : null
},
etc....
]
}
This key explains the response above
| Field | Type | Description |
| notificationSystemLink | String | This will turn the title of the Targeted Notifications window (My Inbox) into a clickable link to your notification system. This is an optional field and can be left blank or null. |
| numNewNotifications | Integer | The total number of new notifications in the response. OneCampus uses this number to update the badge on our display to inform users when they have new notifications to view. |
| date | long | The date of the notification as a UNIX timestamp |
| id | Integer | The id of the notification. OneCampus will send back the ids of read notifications so that the notification system can mark them appropriately and update the newMessage flag. This number should be unique to your institution’s notification system. No two notifications should ever have the same id. |
| message | String | The message to deliver to the user |
| newMessage | Boolean | Indicator used by OneCampus to highlight the notification as new to the user. |
| sender | String | Who, or what system, the notification is from |
| subject | String | The subject of the notification |
| link | String | This is an optional field where you can add a link inside of the message to take your users to more information concerning the notification. |
| linkText | String | This is an optional field used in conjunction with the link field that lets you set the text for the link for more information concerning the notification. |
Marking Notifications as Read
When the user closes the notifications view dialog, OneCampus will send a POST request in the form of {NOTIFICATIONS-ENDPOINT-URL}?user=r8NOAzIn83+UtvMwvRL5yDBchFQZSg+9i2Fynucokqs=×tamp=1482002182566
As part of the request, there will be post data in the body that is a list of all the notification IDs that were just read [1,2,3,4,...,34,35]
The response to this POST should be a JSON response similar to the original GET request in that it will include all notifications again but with an updated numNewNotifications count as well as updated ‘newMessage’ indicators for each notification. If there were new notifications between the original GET and the “mark as read” POST OneCampus sends back, those notifications should be included here but with ‘newMessage’ set to ‘true’.
{
"numNewNotifications": 1,
"notifications":[
{
"date":1458327195576,
"id":0,
"message":"",
"newMessage":false,
"sender":"Bursar",
"subject":"Hello, jmartinez! Pay your bill."
},
{
"date": 1465925123822,
"id": 1,
"message": "You must return your book or pay a fine!!",
"newMessage": false,
"sender": "Library",
"subject": "Hello, jmartinez! Your book is now overdue."
},
....
{
"date": 1465925123822,
"id": 36,
"message": "Book buyback",
"newMessage": true,
"sender": "Campus Bookstore",
"subject": "Hello, jmartinez! You can now sell your books back."
}
]
}
Once properly configured within your tenant, targeted notifications should begin to pass end user notifications from your campus notification system and appear on the main screen of OneCampus. See screenshot below.
Notes:
Tenant Administrators have the option of customizing the label, borders and font color of the targeted notifications dropdown box.
- Change the label on the notifications dialog display by clicking the Advanced menu > Settings > Notifications Title.
- Change the color of the top and bottom borders of the notifications dialog display by going to Branding > Visual Styles > Notification Header Color.
- Change the font color on the notifications header by going to Branding > Visual Styles > Notification Header Font Color.
- If you have included a notificationSystemLink, “My Inbox” will appear as a clickable link to your notification system, see screenshot below.
- URL’s being passed within a notification will always go at the end of the notification and to the right, see screenshot below.
Related to
Updated