-
Notifications
You must be signed in to change notification settings - Fork 1
Home
The Notifications Building Block (Notifications BB) is the service responsible for managing user notifications in the Rokwire ecosystem. This Building Block is designed to support several notification channels, including push notifications, emails, and in-app inboxes.
API level documentation for this Building Block can be accessed by visiting https://api.rokwire.illinois.edu/notifications/api/doc/ui/. This documentation conforms to the OpenAPI 3.0 standard. For the raw YAML documentation, you can visit https://api.rokwire.illinois.edu/notifications/api/doc.
This Wiki provides an overview of the functionality included in the Notifications Building Block. It includes the following sections:
Push notifications allow admins and services to send notifications to user devices. These notifications can be sent using the POST /admin/message endpoint.
Push notifications are managed using Firebase Cloud Messaging (FCM). In order to enable push notifications, a Firebase project must be created and configured for the client that will receive the notifications. The FIREBASE_AUTH environment variable must then be configured with the corresponding Firebase Admin Service Account.
Messages are the structure used to define a message to be sent to clients as a push notification. There are two types of message which service different purposes.
Notification Messages are the standard message type which include content that will be displayed to the user when they are received. The delivery and display of these messages are handled automatically by the FCM SDK.
Depending on user configurations, users will receive these notifications on their mobile devices as an alert delivered by their mobile operating system even if they are not currently using the app. While this is a very useful feature, it is also potentially disruptive so Notification Messages must be reserved for time-sensitive information that is useful to the user.
Aside from the standard Notification Messages Data Messages may also be sent to silently notify the client application of an event. Data messages are useful when we want to asynchronously notify clients of system updates without disrupting the user with a notification. These messages must be handled manually within the client for them to have any effect. Messages without a subject or body are interpreted as data massages, and will not be stored in the Inbox.
Messages include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | 52338e08-750e-496c-91f1-76b110d0e725 |
| Priority | priority |
int | true | A numerical representation of the message priority | 1 |
| Recipients | recipients |
list (Recipient) | false | A list of recipients for this message | |
| Recipient Criteria List | recipients_criteria_list |
list (Recipient Criteria) | false | A list of criteria for message recipients | |
| Topic | topic |
string | false | The topic to which the message should be sent | weather |
| Subject | subject |
string | false | The subject of the message to be displayed to the user | Rain is coming! |
| Body | body |
string | false | The body of the message to be displayed to the user | Rain will start at 3pm today. Grab an umbrella! |
| Sender | sender |
Sender | false | The sender of this message | |
| Data | data |
map (string : string) | false | Data to be included in the message for interpretation by the client. | {"event_type": "rain", "time": "3:00 PM", "severity": "medium"} |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
Message Recipients include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| User ID | user_id |
string | true | The Account ID of the recipient | cf8a2cc9-48cd-43b3-8003-e6f21c756db2 |
| Name | name |
string | false | The user's name for display purposes | John Doe |
| Notification Disabled | notification_disabled |
bool | true | Flag indicating whether the user has notifications disabled | false |
Message Recipient Criteria include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| App Version | app_version |
string | false | The version of the client app for which users should receive the message | 1.0.0 |
| App Platform | app_platform |
string | false | The platform of the client app for which users should receive the message | John Doe |
Message Senders include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Type | type |
string | true | The type of sender. Options include user and system
|
user |
| User | user |
Core User Reference | false | The user that sent the message if type=user
|
Core User References include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| User ID | user_id |
string | true | The Account ID of the recipient | cf8a2cc9-48cd-43b3-8003-e6f21c756db2 |
| Name | name |
string | false | The user's name for display purposes | John Doe |
Messages may optionally include a Topic which acts as an independent message channel. Users may subscribe to specific Topics that they are interested to receive notifications about related events. Users may subscribe to and unsubscribe from topics using the /topic/{topic}/subscribe and /topic/{topic}/unsubscribe endpoints respectively.
Note that when a message is sent to a topic, it will be sent to everyone who has subscribed to that topic. This means that these messages must be considered to be public.
Topics contain the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Name | name |
string | true | The name of the topic | weather |
| Description | description |
string | true | A description of the purpose of the topic | Updates about weather events |
| Application ID | app_id |
string | false | The unique identifier of the Application with which the item is associated. | dabeb056-7796-408c-aa50-397d760be227 |
| Organization ID | org_id |
string | false | The unique identifier of the Organization with which the item is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
The Notification BB also supports sending email notifications for other services. Emails can be sent using the /intl/mail endpoint.
Emails are sent through integration with an SMTP server. In order to send email notifications, the following environment variables must be configured:
- SMTP_HOST: The host URL of the SMTP server
- SMTP_PORT: The port emails should be sent to on the SMTP server
- SMTP_USER: The user name to be used when connecting to the SMTP server
- SMTP_PASSWORD: The password to be used when connecting to the SMTP server
- SMTP_EMAIL_FROM: The email address to be displayed to the user as the "from" address in emails.
Whenever a notification is sent, the associated Message may also be stored for review in application inboxes. This allows users to review a history of their notifications even if they have been dismissed from their system notification tray.
A user may retrieve their Messages by making a request to the GET /messages endpoint. They may delete messages from their inbox when they are done with them by sending a request to the DELETE /messages endpoint.