Push notifications
Enable push, understand which delivery adapter the SDK picks and why, and diagnose the usual reasons a notification never arrives.
Push is the capability with the most moving parts outside the SDK — platform permission, a token, provider credentials, and a delivery path. Most failures are in one of those four, not in your code.
Enable it#
const result = await ScaleBun.enablePush();This requests permission, acquires a token, registers it against the current identity, and starts listening. Call it when the value is obvious to the user — after they have opted into something worth notifying them about — not on first launch, where it converts poorly and cannot be re-prompted.
Handle notifications#
const unsubForeground = ScaleBun.onForegroundNotification((n) => { // Delivered while the app is open. The OS does not display these for you. showInAppBanner(n);});
const unsubOpened = ScaleBun.onNotificationOpened((n) => { // The user tapped it. Route them to what it was about. if (n.data?.deepLink) navigate(n.data.deepLink);});Both return an unsubscribe function — call it on unmount. Register them before
enablePush() so a notification that arrives during startup is not dropped.
Adapter selection#
The SDK picks a delivery adapter from what your project actually has installed. This is worth understanding because it explains most "push does not work" reports:
| Adapter | Chosen when | Notes |
|---|---|---|
| RNFirebase messaging | @react-native-firebase/messaging present and recent enough | The usual path |
| Native bridge | A Firebase config file exists but RNFirebase JS is absent or too old | Ships inside this SDK; available after a rebuild |
| Manual | You supply tokens yourself | For a custom delivery stack |
| Noop | Nothing usable found | Push silently does nothing |
Noop is the failure mode to watch for. It does not error — it just never delivers. Check which adapter you got:
ScaleBun.push.status(); // { adapter, usable, reason, token }The reason field says why an adapter was rejected, which is normally the fastest
path to a fix.
Diagnose before debugging#
The SDK ships a CLI that replicates the selection logic against your project on disk and prints the exact gap:
npx scalebun doctorIt checks React Native version, the new-architecture flag, RNFirebase version, Firebase config files and the Android manifest. It imports nothing from the SDK runtime, so it works before your first build and in CI.
Manual token delivery#
If you run your own push infrastructure:
ScaleBun.push.setToken(tokenFromYourStack);ScaleBun.push.emitForeground(message);ScaleBun.push.emitNotificationOpened(message);setToken also syncs the token to the backend, so campaigns can target the device.
Rich notifications#
@notifee/react-native is an optional peer dependency. With it you get grouped,
styled and action-bearing notifications; without it delivery still works and display
is basic. Nothing warns you it is missing — it is optional by declaration.
Teardown#
ScaleBun.push.teardown();Removes all listeners. Needed only if you are tearing the SDK down inside a running process, such as in a test harness.
Checklist when nothing arrives#
ScaleBun.push.status()— is the adapternoop, orusable: false?Was permission actually granted? A denied prompt cannot be re-shown.
Is there a token?
ScaleBun.push.getToken()Are FCM/APNs credentials configured under Workspace → Integrations?
iOS: is the app signed with an entitlement that matches the APNs key, and are you on a real device? The simulator does not receive remote push.
Related#
Full push namespace reference — all 6 members.
Engage — in-app messages, which need no OS permission.
Troubleshooting — push not delivered.