Push Notifications - Sublay Documentation

Push Notifications lets your app deliver native OS push notifications to users on iOS (via APNs), Android (via FCM), and the browser (via Web Push) — all from a single server-side call. Sublay stores each user’s registered devices, fans a message out to every platform, and prunes stale tokens automatically.

Requires the push bundle. Install it from your project’s Database page in the dashboard before using any push feature. See Bundles for details.

How It Works

Configure credentials in the dashboard — paste your APNs .p8 key, FCM service account JSON, or enable Web Push (keypair generated server-side).
Register devices — your client app calls register() from usePushRegistration at a moment that makes sense for your UX (settings screen, first-run prompt, etc.). The SDK handles permission, token retrieval, and server registration.
Send notifications — your backend calls sublay.push.send({ userIds, title, body, data }). Sublay fans the message out to every registered device for those users across all platforms.

Dashboard Setup

Installing the bundle

Open Database → Bundles in the dashboard and install push. Once provisioning completes, the Push Notifications settings page becomes active.

Configuring providers

Go to Settings → Push Notifications in the dashboard. Configure each platform you want to support: APNs (iOS)

Field	Description
Key ID	The 10-character key identifier from your Apple Developer account
Team ID	Your Apple Developer team ID
Bundle ID	Your app’s bundle identifier (e.g. `com.example.myapp`)
.p8 key	Contents of the `.p8` private key file downloaded from Apple
Production	Toggle for sandbox vs. production APNs gateway (defaults to production)

FCM (Android) Upload or paste your Firebase service account JSON. This is the file downloaded from the Firebase console under Project Settings → Service Accounts → Generate new private key. Web Push No credentials to paste — click Enable. Sublay generates a VAPID EC keypair server-side and stores the private key encrypted. Only the public key is returned and displayed; it is also available via the unauthenticated GET /vapid-public-key endpoint for use in your service worker.

Automatic push settings

Sublay can fan a push out automatically whenever an in-app notification is created (a new comment, reply, mention, reaction, follow, connection, RSVP-event change, space-membership approval) or a chat message is sent — no push.send() call required. The Settings → Push Notifications page lets you tune what those automatic pushes look like per event type:

Setting	Scope	Description
Body template	Per event type	The notification body, with a `{variable}` palette specific to each event. Ships with sensible defaults.
Title template	Per event type	An optional title line, interpolated against the same `{variable}` palette as the body. Ships empty — an unset title renders as an empty string, so titles are opt-in.
Default delivery	Project-wide	A default `{ sound, channelId, priority }` applied to every automatic push.
Delivery override	Per event type	Overrides the project default per field for a single event type. A present field wins; an absent one inherits the default.

These settings affect only the automatic path. The manual push.send() call already accepts title, sound, channelId, priority, and everything else directly. See Automatic Pushes below for the full delivery-config, title-template, and tap-routing contract.

Test-send UI

Each provider card in the dashboard includes a Send Test Push panel. Supply a platform, a device token or subscription, a title, and a body, then click Send Test Push to verify credentials before shipping.

Client SDK — Registering Devices

Use usePushRegistration with the adapter for your platform. Call register() in response to a deliberate user action — not on mount — because requesting OS push permission is a one-shot prompt that users cannot undo.

// Expo
import { usePushRegistration } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo";

function SettingsScreen() {
  const { register, registering } = usePushRegistration(expoPushTokenAdapter);
  return <Button onPress={register} loading={registering} title="Enable notifications" />;
}

// Bare React Native
import { usePushRegistration } from "@sublay/core";
import { reactNativePushTokenAdapter } from "@sublay/react-native";

const { register } = usePushRegistration(reactNativePushTokenAdapter);

// Web (browser)
import { usePushRegistration } from "@sublay/core";
import { webPushTokenAdapter } from "@sublay/react-js";

const { register, unregister } = usePushRegistration(webPushTokenAdapter);

The web adapter requires a service worker. Register one before calling register(). See SDK Reference → Push Notifications for per-platform setup and usePushRegistration for the full hook API.

Server SDK — Sending Notifications

Call client.push.send() from your backend whenever you want to notify users:

import { SublayClient } from "@sublay/node";

const sublay = await SublayClient.init({
  projectId: process.env.SUBLAY_PROJECT_ID!,
  apiKey: process.env.SUBLAY_SERVICE_KEY!,
});

const result = await sublay.push.send({
  userIds: ["usr_abc123", "usr_def456"],
  title: "You have a new match!",
  body: "Tap to see who liked your post.",
  data: { screen: "matches" },
});

for (const [userId, devices] of Object.entries(result.results)) {
  if (devices.length === 0) {
    console.log(`${userId} has no registered devices`);
  } else {
    console.log(`${userId}:`, devices);
  }
}

A single call fans the notification out to all platforms. Capped at 100 user IDs per request. See Node SDK — Push Notifications for the full module reference.

A common pattern is to bridge Sublay’s in-app notifications to push: subscribe to the notification.created webhook and call push.send() when it fires. See Webhooks → Push Notification Bridge.

Rich Notification Payloads

Beyond title, body, and data, push.send() accepts optional fields for sound, badges, images, grouping, priority, and lifetime. Each maps to the native APNs / FCM / Web Push capability and is silently ignored on platforms that don’t support it — so you can set subtitle (iOS-only) and channelId (Android-only) in the same call without branching.

await sublay.push.send({
  userIds: ["usr_abc123"],
  title: "New message",
  body: "Alice sent you a message",
  data: { conversationId: "conv_xyz789" },
  sound: "notification.wav",   // custom sound
  channelId: "messages",       // Android channel (see below)
  badge: 3,                    // iOS app-icon badge
  tag: "conv_xyz789",          // collapse a conversation into one notification
  priority: "high",
});

Field	Platforms	Notes
`sound`	iOS, Android, Web	Filename of a bundled sound. On Android 8+ the channel owns the sound — see below.
`badge`	iOS	App-icon badge count. Your backend supplies the number; Sublay tracks no unread state.
`channelId`	Android	Notification channel id. Created client-side.
`priority`	iOS, Android	`"high"` (default) wakes the device; `"normal"` is power-considerate.
`subtitle`	iOS	Line under the title.
`imageUrl`	iOS, Android, Web	Big-picture image. iOS needs a Notification Service Extension — see below.
`tag`	Android, Web	Display-replace key so notifications collapse instead of stacking.
`collapseId`	iOS, Android	Transport-level collapse — a newer push supersedes an undelivered one.
`threadId`	iOS	Notification grouping.
`ttl`	iOS, Android	Time-to-live in seconds for offline devices.
`mutableContent`	iOS	Enables your Notification Service Extension. Set automatically when `imageUrl` is present.

Client-side requirements

Three of these need setup in your app — Sublay forwards the field but cannot do this part for you:

Android sound → notification channels

On Android 8+ the notification channel owns the sound, importance, and vibration — the payload can’t override it. Create the channel once in your app (with the bundled sound) and pass its id as channelId:

import * as Notifications from "expo-notifications";

await Notifications.setNotificationChannelAsync("messages", {
  name: "Messages",
  importance: Notifications.AndroidImportance.HIGH,
  sound: "notification.wav", // bundled in the app
});

Then push.send({ ..., channelId: "messages", sound: "notification.wav" }). The sound field alone is only a pre-Android-8 fallback. Sublay does not create channels for you.

iOS images → Notification Service Extension

iOS does not download remote images from the payload on its own. To show imageUrl on iOS, add a Notification Service Extension to your app that reads the URL from the notification payload, downloads it, and attaches it. Sublay sets mutable-content automatically whenever imageUrl is present so the extension is allowed to run. Android and Web render imageUrl with no extra work.

Web rendering → your service worker

Sublay ships no service worker — your app’s own SW renders web notifications. The server forwards the web-renderable fields (sound, image, tag) in the push JSON; your push event handler decides how to display them via registration.showNotification(...).

Automatic Pushes

Whenever Sublay writes an in-app notification (a new comment, reply, mention, reaction, milestone, follow, connection request/accept, RSVP-event invite/update/cancel, or space-membership approval) or a chat message is sent, it can fan a native push out to the recipient’s registered devices automatically — you don’t call push.send() for these. What each automatic push looks like is configured per project on the Settings → Push Notifications page.

Everything in this section applies to the automatic path only. The manual push.send() call takes title, body, data, sound, channelId, priority, and the rich fields directly and is unchanged.

Title & body templates

Each event type has a body template (shipped with sensible defaults) and an optional title template. Both are interpolated against the same per-event {variable} palette shown next to each row in the dashboard. The title template ships empty for every event type — an unset title renders as an empty string, which is the historical behavior. Set a title only for the events where you want one; leaving it blank is a no-op.

# Example (dashboard, entity-comment)
Title:  New comment
Body:   {initiatorUsername} commented on your post

Delivery: sound, channel & priority

You can set a project-wide default delivery block and, optionally, a per-event override:

Default — a single { sound, channelId, priority } applied to every automatic push.
Override — a per-event-type { sound, channelId, priority }. Any field you set on the override wins for that event; any field you leave unset inherits the project default. Precedence is per-event override → project default → none.

Field	Platforms	Notes
`sound`	iOS, Android, Web	Filename of a bundled sound. On Android 8+ the notification channel owns the sound — see Android sound → notification channels.
`channelId`	Android	Notification channel id. Created client-side; omitted from the web/iOS payloads.
`priority`	iOS, Android	`"high"` wakes the device; `"normal"` is power-considerate.

These are the same three fields push.send() accepts, wired to the automatic path. The other rich fields (badge, imageUrl, tag, etc.) are configurable on the manual path only.

Tap-routing `data`

Every automatic push carries a flat data object of string identifiers so your app’s tap handler can deep-link to the right screen. All data values are flat top-level strings (FCM coerces data values with String(), so nested objects are not used). Two keys are on every automatic push:

Key	Value
`type`	The event type, e.g. `entity-comment`, `new-follow`, `event-invite`, `message`.
`action`	A canonical routing hint — one of `open-comment`, `open-entity`, `open-profile`, `open-space`, `open-event`, or `open-conversation` (message path).

Beyond type and action, each push forwards every identifier form for each object the notification references, so you can route on whichever id your app uses (UUID, short id, foreign id, slug, or username). Per referenced object:

Object	Keys forwarded
Entity	`entityId`, `entityShortId`, `entityForeignId`
Comment	`commentId`, `commentForeignId` (comments have no short id)
Space	`spaceId`, `spaceShortId`, `spaceSlug`
RSVP event	`eventId`, `eventShortId`
Initiator (the acting user)	`initiatorId`, `initiatorUsername`, `initiatorForeignId` (users have no short id)
Connection	`connectionId`

Which of those apply depends on the event type:

Event type(s)	`action`	`data` identifiers (beyond `type`/`action`)
`entity-comment`, `comment-reply`, `comment-mention`, `comment-reaction`, `comment-reaction-milestone-specific`, `comment-reaction-milestone-total`	`open-comment`	Entity + Comment + Space keys (+ Initiator, except on milestones)
`entity-mention`, `entity-reaction`, `entity-reaction-milestone-specific`, `entity-reaction-milestone-total`	`open-entity`	Entity + Space keys (+ Initiator, except on milestones)
`new-follow`	`open-profile`	Initiator keys
`connection-request`, `connection-accepted`	`open-profile`	`connectionId` + Initiator keys
`space-membership-approved`	`open-space`	Space keys
`event-invite`, `event-updated`, `event-cancelled`	`open-event`	RSVP-event + parent-Space keys + Initiator keys
`message` (chat)	`open-conversation`	`conversationId`, `messageId`

Content and RSVP-event notifications also carry the parent space. A notification about an Entity or Comment (a “content notification”) or an RSVP-event notification additionally forwards the parent Space id set (spaceId, spaceShortId, spaceSlug) when the subject lives in a space, so you can route within a space. Don’t confuse the message event type or an RSVP Event (the data model) with the generic idea of a “notification event.”

These data keys are additive and non-breaking. Existing tap handlers that ignore unknown keys are unaffected — nothing that was present before was removed or renamed. A key whose underlying value is absent (e.g. a user with no foreignId, a space with no slug) is simply omitted rather than sent empty.

The chat-message path builds its data from the send context rather than notification metadata, so it always carries exactly { type: "message", action: "open-conversation", conversationId, messageId }.

Device Lifecycle

Re-registration: registering the same physical device again (same token or endpoint) updates the existing record instead of duplicating it.
Device reassignment: if the same device is registered by a different user (e.g. a shared device after logout/login), the record is reassigned to the new user.
Stale token cleanup: tokens or subscriptions permanently rejected by APNs, FCM, or Web Push during a send are automatically deleted — no separate cleanup pass is needed.
Explicit logout: call unregister() in your logout flow so the device stops receiving notifications after sign-out.

References

Everything related to push notifications across the docs:

SDK Reference — Push Notifications

Per-platform client setup for Expo, React Native, and Web

usePushRegistration

Request permission, register, and unregister the current user’s device

Node SDK — Push Notifications

The push.send() server module reference

Webhooks — Push Bridge

Forward notification.created events to push

API Endpoints

Register Device

POST /push-notifications/devices

Deregister Device

DELETE /push-notifications/devices

Send Push

POST /push-notifications/send

Get VAPID Public Key

GET /push-notifications/vapid-public-key

​How It Works

​Dashboard Setup

​Installing the bundle

​Configuring providers

​Automatic push settings

​Test-send UI

​Client SDK — Registering Devices

​Server SDK — Sending Notifications

​Rich Notification Payloads

​Client-side requirements

​Automatic Pushes

​Title & body templates

​Delivery: sound, channel & priority

​Tap-routing data

​Device Lifecycle

​References

SDK Reference — Push Notifications

usePushRegistration

Node SDK — Push Notifications

Webhooks — Push Bridge

​API Endpoints

Register Device

Deregister Device

Send Push

Get VAPID Public Key

How It Works

Dashboard Setup

Installing the bundle

Configuring providers

Automatic push settings

Test-send UI

Client SDK — Registering Devices

Server SDK — Sending Notifications

Rich Notification Payloads

Client-side requirements

Automatic Pushes

Title & body templates

Delivery: sound, channel & priority

Tap-routing `data`

Device Lifecycle

References

API Endpoints