Notifications and Announcements

Configure and manage the notification system in Testify, including push notifications, in-app alerts, email notifications, and user preferences.

Overview

Testify provides a multi-channel notification system that delivers alerts through three channels: in-app notifications (with real-time SSE delivery), push notifications (mobile and web), and email. Teachers and admins can send custom announcements to students, classes, or the entire organization.

Notification Channels

In-App Notifications

In-app notifications appear in the notification bell icon in the platform header. They are delivered in real-time via Server-Sent Events (SSE), so users see new notifications instantly without refreshing the page.

• Visible in the notification dropdown
• Include unread count badge
• Can be marked as read individually or all at once
• Can be deleted by the user
• Persist until the user dismisses them

Push Notifications

Push notifications reach users on their mobile devices and browsers even when they are not actively using Testify.

Mobile Push:

• Requires the user to register a device token
• Supports Android and iOS platforms
• Delivered via the platform's push notification service

Web Push:

• Uses the Web Push API with VAPID keys
• Users subscribe through the browser's notification permission prompt
• Works even when the browser tab is closed

Email Notifications

Email notifications are sent for important events and custom announcements (when the sender opts to include email). Emails use organization branding (colors, name, reply-to address) when available.

Sending Announcements

Teachers, managers, and admins can send custom notifications to students.

Sending to Specific Students

1. Navigate to "Notifications" > "Send Announcement"
2. Enter the "Title" -- a short headline for the notification
3. Enter the "Message" -- the body text of the announcement
4. Under "Recipients", select "Specific Students"
5. Check the students you want to notify from the list
6. Optionally toggle "Also send via email" to include email delivery
7. Click "Send"

Sending to a Class

1. Navigate to "Notifications" > "Send Announcement"
2. Enter the "Title" and "Message"
3. Under "Recipients", select "By Class"
4. Choose one or more classes from the dropdown
5. Click "Send"

All students enrolled in the selected classes will receive the notification.

Sending to a Section

1. Navigate to "Notifications" > "Send Announcement"
2. Enter the "Title" and "Message"
3. Under "Recipients", select "By Section"
4. Choose one or more sections
5. Click "Send"

Sending to All Students

1. Navigate to "Notifications" > "Send Announcement"
2. Enter the "Title" and "Message"
3. Under "Recipients", select "All Students"
4. Click "Send"

If no specific students, classes, or sections are selected, the notification is sent to all users in the sender's organization.

Tip: Attach an exam to the notification by selecting an "Exam" from the dropdown. This links the notification to the exam in the student's notification list.

Delivery Report

After sending, the system returns:

• Notifications Sent -- number of in-app notifications created
• Push Sent -- number of push notifications delivered
• Emails Sent -- number of emails sent (if email was enabled)

Viewing Notifications (User Perspective)

Notification Bell

1. Click the bell icon in the top navigation bar
2. The dropdown shows recent notifications with:
   • Title and message
   • Linked exam title (if applicable)
   • Timestamp
   • Read/unread status
3. The badge shows the unread count

Notification List

1. Click "View All" in the notification dropdown
2. The full notification list shows all notifications with pagination
3. Use "Mark All as Read" to clear the unread count

Marking as Read

• Click on a notification to mark it as read
• Use the "Mark All Read" button to mark all notifications as read at once
• Send specific notification IDs to mark only selected ones as read

Deleting Notifications

1. Find the notification in your list
2. Click the "Delete" (trash) icon
3. The notification is permanently removed

Configuring Push Notifications

Mobile Device Registration

Mobile apps register push tokens automatically when users log in. The system stores:

• Push token
• Platform (Android/iOS)
• Device type (mobile/tablet)

Tokens are updated when users log in on a new device and deactivated when they log out.

Web Push Subscription

1. When a user visits Testify in a browser, the system requests notification permission
2. If granted, the browser generates a push subscription
3. The subscription is stored with:
   • Endpoint URL
   • P256DH key
   • Auth key
4. Users can unsubscribe at any time through browser settings or the "Notification Preferences" page

VAPID Key Configuration

Web push requires VAPID (Voluntary Application Server Identification) keys.

1. Generate VAPID keys using a web-push library
2. Set the following environment variables on the server:
   • VAPID_PUBLIC_KEY -- shared with the browser
   • VAPID_PRIVATE_KEY -- kept on the server
   • VAPID_EMAIL -- contact email for the push service
3. The public key is served at the /api/notifications/vapid-key endpoint

Tip: VAPID keys only need to be generated once. Changing them invalidates all existing browser subscriptions.

Notification Preferences

Users can customize which notifications they receive through the preferences panel.

Accessing Preferences

1. Click your profile avatar in the top-right corner
2. Select "Notification Preferences"
3. Or navigate to "Settings" > "Notifications"

Available Preferences

Email Preferences

Preference	Default	Description
Exam Published	On	Email when a new exam is published
Exam Results	On	Email when exam results are available
Certificates	On	Email when a certificate is issued
Achievements	On	Email for badge and achievement unlocks
System	On	System announcements and updates

Push Preferences

Preference	Default	Description
Exam Published	On	Push when a new exam is assigned
Exam Results	On	Push when results are ready
Achievements	On	Push for gamification events
System	On	System-level push notifications

General Preferences

Preference	Default	Description
In-App All	On	Master toggle for all in-app notifications
Quiet Hours Start	None	Start time for notification silence
Quiet Hours End	None	End time for notification silence

Updating Preferences

1. Toggle individual preferences on or off
2. Set quiet hours to suppress notifications during specific times
3. Click "Save Preferences"

Tip: Quiet hours only affect push notifications and email. In-app notifications are still stored and visible when the user logs in.

Real-Time Delivery (SSE)

Testify uses Server-Sent Events to deliver notifications in real-time. When a notification is created, it is broadcast to the recipient's active browser sessions via the SSE connection.

How It Works

1. When a user opens Testify, the browser opens an SSE connection to /api/notifications/sse
2. The connection stays open as long as the browser tab is active
3. When a new notification is created for the user, it is pushed through the SSE channel
4. The notification bell updates its count and the notification appears in the dropdown immediately

Email Templates and Branding

When notifications are sent via email, Testify applies organization branding.

Branding Elements

• Primary Color -- used for headings and call-to-action buttons
• Organization Name -- appears in the email footer
• From Name -- the sender name shown in the email client
• Reply-To Address -- where replies are directed

Branding is resolved from the sender's organization settings. If no branding is configured, platform defaults are used.

Notification Types

Type	Trigger	Channels
EXAM_PUBLISHED	Exam is published and assigned	In-app, Push, Email
EXAM_REMINDER	Exam is approaching its start time	In-app, Push
EXAM_RESULTS	Exam results are released	In-app, Push, Email
CERTIFICATE_ISSUED	Certificate is generated	In-app, Email
ACHIEVEMENT	Badge or streak earned	In-app, Push
CUSTOM	Admin/teacher sends announcement	In-app, Push, Email (optional)
SYSTEM	Platform update or maintenance	In-app, Push, Email

Troubleshooting

Push Notifications Not Arriving

• Verify the device token is registered (check "Devices" in user settings)
• Ensure the browser has granted notification permission
• Check that VAPID keys are correctly configured on the server
• Verify push notification preferences are enabled for the user

Email Notifications Not Sending

• Check that the email service is configured (SMTP settings)
• Verify the user's email address is correct
• Check email preferences -- the user may have disabled email for that event type
• Look for email delivery errors in the server logs

SSE Connection Dropping

• SSE connections may drop due to network issues or proxy timeouts
• The browser automatically reconnects when the connection is lost
• If notifications are missing, refresh the page to re-establish the SSE connection