Push Notifications

Push notifications deliver alerts to a user's device even when the application is not open. ActiveManage uses the standard Web Push protocol so notifications work on Android phones, desktop browsers, and iOS (16.4+) Safari without requiring a native app.

Prerequisites

• HTTPS is required (Web Push will not work on plain HTTP, even on localhost beyond the dev exemption).
• The Service Worker must be installed (see the PWA section).
• VAPID keys configured under Site Settings → Communication → Push Notifications.

Generating VAPID Keys

The settings page has a Generate VAPID keys button. Click it once; the public key is embedded in client requests, the private key never leaves the server. Rotating the keys invalidates existing subscriptions so users have to re-enrol.

End-User Enrolment

1. The user opens the application and is offered a banner: “Turn on notifications for new chat messages and booking confirmations?”.
2. If they accept, the browser prompts for permission (one time).
3. On allow, the subscription endpoint and keys are sent to the server and saved against the user.

Example Use Cases

• Field workers: Get a push when a new job is assigned, even when the app is closed.
• Marketplace sellers: Receive notifications for new orders so they can ship quickly.
• Educational platform: Students get notified when a lecture is published or an assignment is due.

Note: iOS requires the user to install the PWA to their home screen first before push notifications can be enrolled — there's no in-Safari push for ordinary tabs. Surface a friendly “Add to Home Screen” guide for iOS visitors.

Users rarely want every event pushed to their phone. Channels let you group notification types so users can opt in to the ones that matter to them.

Defining Channels

Go to Site Settings → Communication → Push Notifications → Channels. Each channel has a name, an icon, a default-enabled flag and an importance level (Low, Default, High, Urgent).

Channels by Importance

• Urgent: Always shows full-screen alerts and uses sound. Reserve for true emergencies like “door alarm triggered”.
• High: Visible heads-up notification with sound. Good for new chat messages, fresh orders, time-critical bookings.
• Default: Standard notification, gentle sound. Use for routine reminders.
• Low: Silent, appears in the notification tray. Good for marketing or low-priority updates.

Example Channel Sets

• Healthcare app: Channels for “Appointment reminders” (Default), “Test results available” (High), “Clinic announcements” (Low).
• Logistics app: “New job assigned” (High), “Job status changed” (Default), “Monthly summary” (Low).
• Marketplace: “New order” (Urgent), “Buyer message” (High), “Platform news” (Low).

Tip: Default channels that are enabled out of the box should be ones users will reliably want. Anything mildly noisy or marketing-flavoured should default off so users can opt in deliberately.

The service worker is the small JavaScript file that runs in the background of the user's browser. It is the component that actually receives push notifications when the application's tab is closed, and that decides how to display them.

How It's Installed

The platform ships a default service worker at /sw.js. On every page load the application registers it if it isn't already installed. Browsers cache the file aggressively; you bump its embedded version string to force an update.

Customising Notifications

The service worker calls a hook function before showing each notification. You can override:

• Title: Default is the channel name; override to show the sender or context.
• Body: The main message. Keep under 200 characters — long bodies get truncated by the OS.
• Icon and badge: Use a 192×192 PNG for the icon and a monochrome PNG for the badge.
• Action buttons: Up to two quick actions (e.g. “Mark as read”, “Reply”). Each is wired to a click handler in the service worker.

Worked Examples

• Chat notification: Title is the sender's name, body is the message text, icon is the sender's avatar, action buttons are “Reply” (opens chat thread) and “Mark as read”.
• Booking reminder: Title is “Appointment in 30 minutes”, body lists location and patient, action button is “View booking”.
• Order update: Title is the order number, body is the new status, badge shows the platform logo.

Note: Service workers can only be served from HTTPS origins. They are scoped to the path they were registered from — the default /sw.js has root scope and controls every page on the origin.