Notifications

Local notifications, action buttons, Android channels, and push tokens on iOS and Android

One.Notifications shows notifications from your app, schedules them for later, adds action buttons, and gets the device’s push token. On iOS it is the UserNotifications framework; on Android it is NotificationManager for posting and AlarmManager for scheduling, with Firebase Cloud Messaging for push tokens.

It covers the whole local path: permission, scheduling, how a notification shows while the app is open, and the tap that brings people back. Remote push delivery itself comes from your server through APNs or FCM; One hands you the token to send it to.

Usage

Turn notifications on in your app config, then run prebuild:

import { one } from 'one/vite'

export default {
  plugins: [one({ native: { app: { name: 'Tea', notifications: {} } } })],
}

Then ask for permission and schedule:

import { One } from 'one'

async function remindInFiveMinutes() {
  const { granted } = await One.Notifications.requestPermissions()
  if (!granted) return
  await One.Notifications.schedule({
    identifier: 'tea',
    content: { title: 'Tea', body: 'Your tea is ready' },
    trigger: { type: 'timeInterval', seconds: 300 },
  })
}

The identifier names the request, so scheduling tea again replaces it rather than adding a second reminder.

How it works

Config. notifications: {} makes prebuild mark the app as using One’s notifications: on iOS it adds an Info.plist flag that installs One’s notification delegate at launch; on Android it adds the notification permission and the receiver that delivers alarms and taps. Without it, One installs nothing, so an app that uses another push library keeps that library’s delegate.

Permission. requestPermissions shows the system prompt on iOS and, on Android 13 and later, asks for the notification permission. Older Android versions have no runtime prompt, so it resolves the current status.

Scheduling. A null trigger posts at once. timeInterval waits a number of seconds and can repeat; date fires at a time, and a past date posts at once. iOS hands the request to the system. Android stores it, sets an inexact alarm with setAndAllowWhileIdle, and posts when the alarm fires; the schedule survives restarts, and after a reboot future alarms are set again, repeats start over from boot, and one-time reminders that expired while the device was off are dropped.

While the app is open. When a notification arrives in the foreground, native code asks JavaScript how to show it. setHandler answers with a banner, list, sound, and badge choice. With no handler set, it shows in full; with the handler set to null, it stays hidden. If the handler throws or takes more than 3 seconds, native shows it in full rather than dropping it. If nothing in JavaScript listens yet, it shows at once. Every foreground arrival also fires addReceivedListener.

Taps. A tap fires addResponseReceivedListener with the notification and the action identifier: the action’s own identifier for a button, or DEFAULT_ACTION_IDENTIFIER for the body. A tap that launches the app lands before JavaScript is running, so native keeps it, and getLastResponse returns it synchronously on start. On iOS, One’s delegate installs as the app finishes launching, before that tap can arrive.

Push tokens. With notifications: { push: true }, iOS gets the APNs entitlement and calls registerForRemoteNotifications, and the token comes back as lowercase hex. Android compiles in Firebase Messaging and returns the FCM registration token. Without push, Firebase stays out of the Android app and getDevicePushToken rejects on both platforms.

API reference

Permission and badge

Scheduling

Events

Categories, channels, and push

Platform differences

Limits and gotchas

• Android alarms are inexact. One uses setAndAllowWhileIdle, which needs no exact alarm permission, so doze can delay a reminder by minutes. Do not use it for alarm clock timing.
• Repeating intervals on iOS are at least 60 seconds. A shorter repeating interval rejects with E_NOTIFICATIONS_TRIGGER.
• Create Android channels first. Android shows notifications only in channels. Scheduling onto an unknown channelId posts to a channel named Default that One creates. A channel’s settings apply when it is created; after that people own them in system settings, and setChannel cannot change them.
• On Android the channel decides. shouldShowBanner raises the notification’s priority, but the channel’s importance controls whether a banner appears. shouldSetBadge does nothing there.
• Read the launching tap on start. A tap that opens the app never reaches a listener. Call getLastResponse once JavaScript starts, then clearLastResponse so you do not handle it twice.
• Category identifiers are strict. They must be non-empty and contain no : or -; anything else throws, the same on every platform. A notification whose category is unknown posts without buttons.
• data carries plain JSON. Strings, numbers, booleans, null, arrays, and objects pass through. Functions and undefined are dropped, and a Date arrives as an empty object, so send timestamps as numbers.
• Set the APNs environment for release. iOS uses the development environment unless apsEnvironment is production, which builds for TestFlight and the App Store need.
• Web is inert. Permission reads resolve denied, lists are empty, listeners never fire, and schedule rejects. Arguments are still checked, so bad input throws on web too.

Examples

import { useEffect } from 'react'
import { One } from 'one'

function useQuietChat(openChatId: string | null) {
  useEffect(() => {
    One.Notifications.setHandler({
      handleNotification: (notification) => {
        const chatId = notification.request.content.data.chatId
        const visible = chatId !== undefined && chatId === openChatId
        return {
          shouldShowBanner: !visible,
          shouldShowList: true,
          shouldPlaySound: !visible,
          shouldSetBadge: false,
        }
      },
    })
  }, [openChatId])
}

Messages for the open chat still land in the list but make no banner or sound. The handler answers synchronously, well inside the 3 second limit.

import { useEffect } from 'react'
import { One } from 'one'

async function registerReply() {
  await One.Notifications.setCategory('message', [
    { identifier: 'reply', buttonTitle: 'Reply', textInput: { placeholder: 'Message' } },
    { identifier: 'read', buttonTitle: 'Mark as read', options: { opensAppToForeground: false } },
  ])
}

function useReplies(send: (chatId: string, text: string) => void) {
  useEffect(() => {
    const subscription = One.Notifications.addResponseReceivedListener((response) => {
      const chatId = response.notification.request.content.data.chatId
      if (response.actionIdentifier === 'reply' && typeof chatId === 'string' && response.userText) {
        send(chatId, response.userText)
      }
    })
    return () => subscription.remove()
  }, [send])
}

Notifications with categoryIdentifier: 'message' get both buttons. Mark as read does not open the app, and the typed reply arrives as userText.

import { useEffect } from 'react'
import { One, useRouter } from 'one'

function useNotificationLinks() {
  const router = useRouter()
  useEffect(() => {
    const open = (url: unknown) => {
      if (typeof url === 'string') router.push(url)
    }
    const launch = One.Notifications.getLastResponse()
    if (launch) {
      open(launch.notification.request.content.data.url)
      One.Notifications.clearLastResponse()
    }
    const subscription = One.Notifications.addResponseReceivedListener((response) => {
      open(response.notification.request.content.data.url)
    })
    return () => subscription.remove()
  }, [router])
}

The launching tap and later taps take the same path. Clearing the stored response keeps a remount from opening the screen again.

import { One } from 'one'

async function registerForPush(upload: (token: { type: string; data: string }) => Promise<void>) {
  const { granted } = await One.Notifications.requestPermissions()
  if (!granted) return
  await upload(await One.Notifications.getDevicePushToken())
  One.Notifications.addPushTokenListener(upload)
}

The listener fires only when the token changes later, so read the current one first. This needs notifications: { push: true } in the app config, and on Android your Firebase project file set with android.googleServicesFile.