Local notifications

Schedule on-device reminders that fire without a server round-trip — distinct from remote push.

A local notification is one the device schedules and fires by itself — no server, no delivery infrastructure, no network. Use it for things the app already knows it wants to surface at a future moment: streak reminders, "come back tomorrow" nudges, a timer that just elapsed.

This is different from remote push, where Amba's backend decides when to deliver a notification and routes it to the device. Reach for local notifications when the device owns the timing; reach for push (or a push campaign) when the server does.

Local notifications are an on-device primitive. The Node SDK exposes the same methods but throws a clear error — a server has no device notification framework to schedule against. Nudge users from the server with push instead.

API

// Schedule — returns a handle whose `id` you can cancel later.
const { id } = await Amba.notifications.scheduleLocal({
  id?: string,                 // optional stable id; omit to auto-generate
  title: string,
  body: string,
  data?: Record<string, unknown>,
  trigger:
    | { at: Date }                              // fire once at an absolute time
    | { inSeconds: number; repeats?: boolean }, // fire after a delay (repeat optional)
});
 
// Cancel a scheduled notification by id.
await Amba.notifications.cancelLocal(id);
 
// List everything currently scheduled to fire on this device.
const pending = await Amba.notifications.listScheduledLocal();

The OS notification permission is requested automatically the first time you call scheduleLocal. A declined prompt throws an AmbaApiError with code LOCAL_NOTIFICATIONS_PERMISSION_DENIED.

Quick start

Local notifications use expo-notifications under the hood — the same library you already install for push-token capture. It works in both Expo and bare React Native apps. Install it once:

npx expo install expo-notifications

If it isn't installed, every notifications.* method throws LOCAL_NOTIFICATIONS_UNAVAILABLE with an actionable message — never a silent no-op.

import { Amba } from '@layers/amba-expo'; // or '@layers/amba-react-native'
 
// Remind the user in 12 hours to keep their streak alive.
const { id } = await Amba.notifications.scheduleLocal({
  title: 'Keep your streak alive 🔥',
  body: 'You have a lesson waiting.',
  data: { screen: 'streak' },
  trigger: { inSeconds: 60 * 60 * 12 },
});
 
// Cancel it (e.g. the user completed the lesson early).
await Amba.notifications.cancelLocal(id);
 
// What's still pending?
const pending = await Amba.notifications.listScheduledLocal();

Schedule at an absolute time instead:

const tomorrow9am = new Date();
tomorrow9am.setDate(tomorrow9am.getDate() + 1);
tomorrow9am.setHours(9, 0, 0, 0);
 
await Amba.notifications.scheduleLocal({
  title: 'Good morning',
  body: 'Three goals are waiting for you today.',
  trigger: { at: tomorrow9am },
});

Platform capability differences

Local notifications behave differently across platforms. Amba is honest about this rather than silently degrading.

Platform	Absolute time (`at`)	Delay (`inSeconds`)	Repeats	Fires when app is closed
iOS	✅	✅	✅	✅
Android	✅	✅	✅	✅
Web (Chromium)	✅¹	✅¹	—	✅¹
Web (other browsers)	⚠️²	⚠️²	—	❌²

¹ Requires the experimental Notification Triggers API (TimestampTrigger) plus an active Service Worker, over HTTPS. When present, the notification is handed to the OS and fires even if the tab or browser is closed. The handle reports scheduledVia: 'os-trigger'.

² Without the Triggers API, the web SDK falls back to an in-page timer. The notification fires only while the page stays open — if the user closes the tab before it elapses, it does not fire. This is a hard browser limitation. The handle reports scheduledVia: 'timer' so you can detect the degraded mode and adjust your UX (for example, only schedule short delays, or prefer remote push for anything that must survive a tab close).

The Node SDK throws LOCAL_NOTIFICATIONS_UNAVAILABLE for all three methods — local notifications are a client primitive.

Local vs. remote: which do I use?

Local notification — the device already knows the time. Streak reminders, focus timers, "your download finished." No server round-trip, works offline, fires precisely on iOS/Android.
Remote push / push campaign — the server decides the time, or the content depends on server-side state (a new message arrived, a campaign targets a segment). Survives the app being closed on every platform.

They compose: schedule a local reminder on-device and register for push so the server can still reach the user when it needs to.

Local notifications

API

Quick start

Platform capability differences

Local vs. remote: which do I use?

On this page