Skip to content

DocsProducts

OpenPulse

Products

Push

Notifications to browsers, iPhone and Android apps, with Apple and Google keys kept per realm.

Built Send notifications to your own users: Web Push to your web app, APNs to your iPhone and iPad apps and FCM to your Android apps. You file each device under a subject you name, usually a person's id, and one send reaches every device that subject uses.

Before you start#

Push apps belong to a realm's own sending domain, so turn on Mail for the realm and add a sending domain first. The realm's owner manages Push in the Console under Products → Push. Your server uses the API key it already holds for Mail.

Keys per realm#

Browser notifications work without a provider key. To reach iPhone and Android apps, save your Apple and Google keys on the realm's Push page.

KeyWhat you enter
AppleTeam ID, key ID, bundle IDs and the signing key (.p8)
GoogleThe service account file (.json) and, optionally, the Android packages it covers

A key saved on a realm serves that realm alone, stays sealed on the server and is never shown again. Until a realm saves its own key, its apps send with the account's key where there is one, and the page says so.

Send#

TypeScript
import { OpenPulsePush } from '@openpulse/sdk/push'const push = OpenPulsePush.fromEnv() // PUSH_API_KEY, else the Mail key's namesawait push.send({  app: 'sorvenna',  person: 'user_8f2c',  notification: { title: 'Tour 14 is late', body: 'New arrival 14:20', url: '/tours/14' },  collapse_id: 'tour-14',})

A send names one target: a person, up to 1000 persons, one device or a topic.

ModeCarriesUse it for
alertA title, body and linkWhat a person may read on a lock screen. This is the default.
wakeNothingiPhone and Android apps that fetch from their own backend.
sealedWhat your app sealed for each deviceContent only the receiving app can open.

Push follows the login#

File a device only from a signed-in session, under that session's user id, and only from your backend. Drop the device when the person signs out, before the session ends. On sign-out everywhere and when an account is deleted, call push.devices.remove({ subject: userId }).

TypeScript
// app/api/push/[[...path]]/route.tsimport { OpenPulsePush, createPushHandler } from '@openpulse/sdk/push'const handler = createPushHandler({  push: OpenPulsePush.fromEnv(),  app: 'sorvenna',  publicKey: process.env.PUSH_PUBLIC_KEY!,  userId: async (req) => (await getSession(req))?.user.id ?? null,})export { handler as GET, handler as POST, handler as DELETE }
TypeScript
import { disablePush, enablePush, syncPush } from '@openpulse/sdk/push'const route = { register: '/api/push', serviceWorker: '/sw.js' }await enablePush(route)         // from a tap, while signed inawait syncPush(route)           // on every app startawait disablePush('/api/push')  // the off switch, and on sign-out
TypeScript
// sw.tsimport { handlePushEvents } from '@openpulse/sdk/push/sw'handlePushEvents(self, { icon: '/icon-192.png' })

iPhone and Android apps#

The app hands its token to your backend after sign-in, and your backend files it.

TypeScript
await push.devices.register({  app: 'sorvenna',  transport: 'apns',  subject: userId,  token: apnsToken,  environment: 'production', // sandbox for a development build  bundle_id: 'com.sorvenna.app',})

What the plane keeps#

The title, body, link and data are sealed while a delivery waits and deleted once the last delivery settles. The receipt, with who it went to and each device's state, is kept for 30 days. Nothing tracks whether a notification was opened.

Good to know#

DevicesA subject keeps the ten devices seen most recently per app.
Time to liveOne day by default and 28 days at most.
SizeUnder 3800 bytes for Web Push and under 4 KB for APNs and FCM.
RetriesAfter 10 seconds, 1, 5 and 30 minutes and 2 hours, or when the provider says.
iPhone and iPad on the webiOS 16.4 or later, from a web app added to the Home Screen.
Webhookspush.failed, push.device_removed and push.credentials_failed arrive through your Mail webhooks.