headless lms
Push

APNs, FCM and Web Push

Send push notifications to iOS apps, Android apps and browsers with the push adapter.

@headless-lms/adapter-push implements the PushSender port. It sends straight to each platform's push service, with no third-party push service in between:

ProviderPlatformSent through
apnsiOSHTTP/2 to Apple, or Apple's sandbox for a development build; token auth with the team's .p8 key; the topic is the app's bundle id
fcmAndroidFCM HTTP v1 with the Firebase project's service account
webpushbrowsersthe subscription's endpoint, signed with your VAPID key pair and encrypted with the subscription's keys

When at least one provider is configured, the server registers the push notification channel: categories can offer it, members can switch it on and off, and each notification a member gets by push goes to every device they registered and used in the last 30 days. Without the adapter, or with no provider configured, there is no push channel and devices can't register.

Setup

The adapter reads no environment itself. Your installation parses env into a PushConfig and passes both the config and the adapter:

main.ts
import { PushAdapter } from "@headless-lms/adapter-push";

const push = loadPushConfig();
const container = await createContainer(config, {
  adapters: {
    push,
    pushSender: new PushAdapter(push),
  },
});

push tells the server which providers exist (the device routes refuse an unconfigured provider, and a browser reads the VAPID public key from GET /api/member/push-config); pushSender does the sending.

Registering devices

An app registers its push address after sign-in and on every launch with POST /api/member/devices, and removes it with DELETE /api/member/devices/:deviceId before it signs out.

  • iOS: the APNs device token, with appId the app's bundle id (one of APNS_BUNDLE_IDS) and environment production or sandbox. An app built with Expo registers the native token from getDevicePushTokenAsync, not an Expo push token.
  • Android: the FCM registration token.
  • Browser: subscribe with pushManager.subscribe({ applicationServerKey }) using the key from push-config, then register the subscription's endpoint as the token with its p256dh and auth keys. Register again on pushsubscriptionchange.

What a push carries

Every push has a title and body, rendered from the notification, and data: { notificationId, type, subject, parent, communityId, spaceId, courseId }, so the app can open the item and mark the notification read; courseId names the course of a notification on a course activity. On FCM every data value is a string, with subject and parent JSON-encoded.

A delivery is sent when at least one device accepts it. A network error, a 429 or a 5xx from every device is retried by the workflow engine; an answer that won't change on a retry fails the delivery at once. Devices the provider reports as gone are removed.

Environment variables

These are the variables the reference installation (apps/api) maps to PushConfig. A provider is configured when all of its variables are set; setting only some of them stops the server at startup.

VariableProviderNotes
APNS_TEAM_IDAPNsApple developer team id
APNS_KEY_IDAPNsid of the .p8 key
APNS_KEYAPNsthe .p8 key, \n for newlines
APNS_BUNDLE_IDSAPNscomma-separated bundle ids of the apps the key serves
FCM_SERVICE_ACCOUNTFCMthe Firebase project's service account JSON
VAPID_PUBLIC_KEYWeb Pushfrom npx web-push generate-vapid-keys; the same on every server
VAPID_PRIVATE_KEYWeb Push
VAPID_SUBJECTWeb Pusha mailto: or https: contact

On this page