Push notifications

The client SDK has two responsibilities for push:

1. Register the platform-native push token (APNs on iOS, FCM on Android, web push on browsers) so the server knows where to deliver.
2. Subscribe the user to named topics — message broadcasts ("breaking_news", "weekly_digest") that fan out to every subscribed device.

Actual sends are server-side via the push campaign API or scheduled fan-outs.

Quick start

import { Amba } from '@layers/amba-web';
 
// 1. Get a web push subscription from the browser
const registration = await navigator.serviceWorker.register('/amba-sw.js');
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: 'YOUR_VAPID_PUBLIC_KEY',
});
 
// 2. Register the token with amba
await Amba.push.register(JSON.stringify(subscription), 'web');
 
// 3. Subscribe to a topic
await Amba.push.subscribe('breaking_news');

Operations

register(token, platform, bundleId?)

Records the device's push token against the signed-in user. Call this:

• Once after sign-in, when you first obtain a token.
• Again whenever the platform issues a new token (rotation, app re-install).

platform is one of 'apns' (iOS APNs), 'fcm' (Android Firebase Cloud Messaging), or 'web' (web push). bundleId is required for 'apns' and 'fcm' so the server knows which app the token belongs to.

The call is idempotent — re-registering the same token for the same user is a no-op.

subscribe(topic) / unsubscribe(topic)

Opt the user into a named topic. Topic names match the same identifier shape as collection names (^[a-z][a-z0-9_]*$, up to 64 characters).

await Amba.push.subscribe('breaking_news');
await Amba.push.subscribe('user_segment_engaged');
// ... time passes ...
await Amba.push.unsubscribe('breaking_news');

Topics are a server-side fan-out target: a single send to topic breaking_news reaches every device subscribed to it for the signed-in user, across iOS / Android / web.

Patterns

Re-register on app launch

Push tokens rotate; the platform issues fresh ones periodically. Re-register on every cold start to keep server-side delivery routing accurate:

useEffect(() => {
  void (async () => {
    if (!Amba.isAuthenticated) return;
    const { data: token } = await Notifications.getDevicePushTokenAsync();
    await Amba.push.register(token, Platform.OS === 'ios' ? 'apns' : 'fcm');
  })();
}, []);

Topic opt-in flow

Surface topic subscription as user preference toggles. Persist the toggle state in a collection so the user's choice survives across devices:

async function setBreakingNewsOptIn(opt: boolean) {
  if (opt) {
    await Amba.push.subscribe('breaking_news');
  } else {
    await Amba.push.unsubscribe('breaking_news');
  }
  await Amba.collections.update('user_prefs', userPrefsId, { breaking_news_optin: opt });
}

Permission UX

Always request the OS push permission separately — register only after the user has explicitly granted permission. The SDK's register() will accept a token without permission, but no notification will deliver.

Limits

• Topic count per user: up to 100 simultaneous topic subscriptions per user.
• Topic name: lowercase identifier, up to 64 characters.
• Token freshness: tokens are not validated by the SDK at register time. If a token has been invalidated by the platform (e.g. user uninstalled and reinstalled), pushes to it will silently fail server-side until you re-register with a fresh token.
• Platform requirements: APNs requires the Push Notifications capability in Xcode. FCM requires google-services.json and the Google Services Gradle plugin. Web push requires a service worker and a VAPID key pair.
• No client-side send: client SDKs cannot send pushes; that's the push campaign API or scheduled fan-outs.

Reference

• Client API — push — register / subscribe endpoint reference.
• Admin API — push campaigns — server-side send.
• Auth feature — prerequisite.
• Per-platform quickstarts: Web, React Native, Expo, iOS, Android, Flutter, Unity.