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.
| Key | What you enter |
|---|---|
| Apple | Team ID, key ID, bundle IDs and the signing key (.p8) |
| The 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#
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.
| Mode | Carries | Use it for |
|---|---|---|
alert | A title, body and link | What a person may read on a lock screen. This is the default. |
wake | Nothing | iPhone and Android apps that fetch from their own backend. |
sealed | What your app sealed for each device | Content 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 }).
// 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 }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// 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.
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#
| Devices | A subject keeps the ten devices seen most recently per app. |
| Time to live | One day by default and 28 days at most. |
| Size | Under 3800 bytes for Web Push and under 4 KB for APNs and FCM. |
| Retries | After 10 seconds, 1, 5 and 30 minutes and 2 hours, or when the provider says. |
| iPhone and iPad on the web | iOS 16.4 or later, from a web app added to the Home Screen. |
| Webhooks | push.failed, push.device_removed and push.credentials_failed arrive through your Mail webhooks. |