Уведомления

notifications планирует уведомление на самом устройстве — напоминание на время, ежедневное или показанное прямо сейчас — и ловит тап по нему. Сервер не участвует: уведомление, которое твой бэкенд отправляет пользователю, — дело плагина push (Push). Запланированное уведомление устройство показывает и при закрытом приложении; тап открывает приложение и доходит до onTap.

  • напомнить пользователю в выбранное им время (лекарство, тренировка, дедлайн)
  • ежедневное или еженедельное напоминание в одно и то же время
  • показать уведомление прямо сейчас (загрузка завершилась, твой ход в игре)
  • открыть нужный экран, когда пользователь тапнул по уведомлению, в том числе если тап запустил приложение
  • отменить напоминание или посмотреть список ещё не сработавших
  • запросить разрешение на уведомления раньше или обработать отказ

Платформы: iOS и Android. На десктопе, в вебе и в headless-тестах их нет: notifications.supported равен false, schedule отклоняется, остальное ничего не делает.

Обзор

TypeScript
const remindAt = async (when: Date) => {
  try {
    await notifications.schedule({
      id: 'water',                        // тот же id ещё раз заменит это напоминание
      title: 'Time to drink water',
      body: 'A glass now keeps the headache away',
      at: when,
      repeat: 'daily',
      data: { screen: 'hydration' },
    })
    toast('Reminder set')
  } catch (e) {
    if ((e as Error).message === 'denied') toast('Turn notifications on in Settings')
  }
}

notifications.onTap(tap => {                // пока приложение работает, и тап, который его запустил
  if (tap.data?.screen === 'hydration') Router.push(hydrationScreen)
})

Запланировать уведомление: notifications.schedule

TypeScript
notifications.schedule(request): Promise<string>   // id — твой или сгенерированный

interface NotificationRequest {
  id?: string                   // тот же id, запланированный снова, заменяет прежнее уведомление
  title: string
  body?: string
  at?: Date | number            // когда сработает; нет или в прошлом — показывается сейчас
  repeat?: 'daily' | 'weekly'   // снова каждый день / неделю в это время, пока не отменят (нужен `at`)
  url?: string                  // ссылка, которую приложение откроет по тапу
  data?: { [key: string]: unknown }   // твоё, не больше 2 КБ в JSON; возвращается вместе с тапом
}

schedule показывает уведомление в момент at, а без него — сейчас. repeat повторяет его каждый день или каждую неделю в то же время по часам (в часовом поясе устройства), пока его не отменят; повторяющийся at в прошлом не показывается сейчас — серия начинается с ближайшего наступления этого времени. Первый вызов запрашивает у ОС разрешение на уведомления — первое напоминание, которое ставит пользователь, и есть момент, когда он ждёт диалога, так что спрашивать до этого нечего. Резолвится он id: задай свой, если потом будешь заменять или отменять уведомление (одно напоминание на лекарство, по ключу лекарства), или возьми сгенерированный.

TypeScript
// показать сейчас
await notifications.schedule({ title: 'Export finished', body: 'report.pdf is ready', data: { file: 'report.pdf' } })

// через два часа
await notifications.schedule({ title: 'Your turn', at: Date.now() + 2 * 60 * 60 * 1000 })

// каждый понедельник в 9:00, начиная с ближайшего (в понедельник после 9:00 — со следующей недели)
const monday = new Date()
monday.setDate(monday.getDate() + ((8 - monday.getDay()) % 7))   // ближайший понедельник, меньше недели вперёд (iOS, ниже)
monday.setHours(9, 0, 0, 0)
await notifications.schedule({ id: 'weekly-review', title: 'Weekly review', at: monday, repeat: 'weekly' })
  • Отклоняется с e.message === 'denied', когда пользователь отказал в разрешении (путь назад — permissions.openSettings(), ниже), с 'unavailable' там, где хост не умеет планировать, и ещё до хоста — при отсутствии заголовка, repeat без at или data больше 2 КБ.
  • Уведомление показывает системный баннер, и когда приложение на переднем плане: приложению, которое хочет реагировать на свой таймер, пока оно открыто, нужен таймер, а не уведомление.
  • Android показывает запланированное уведомление в пределах нескольких минут от at (система сама группирует срабатывания; точность до секунды не обещана); iOS — в срок.
  • У повторяющегося уведомления на iOS нет даты начала: первый раз оно срабатывает в ближайшее наступление времени at (daily) или дня недели и времени (weekly), считая от сейчас, так что at больше чем на день (неделю) вперёд срабатывает там раньше at — Android ждёт at. Держи повторяющийся at в пределах одного периода от сейчас, как понедельник выше. Серия, которая должна начаться позже (курс с 1-го числа), — это разовое уведомление в её первый день, а повторяющееся, под тем же id, планируется, когда приложение в следующий раз запустится после него — из onTap или при следующем старте.
  • Одно приложение — одно расписание: во вьюере le.codes у каждого проекта своё, так что cancelAll и pending никогда не трогают уведомления другого проекта.

Поймать тап: notifications.onTap

TypeScript
notifications.onTap(handler: (tap: NotificationTap) => void): { close(): void }

interface NotificationTap { id: string, title: string, body?: string, url?: string, data?: { [key: string]: unknown } }

onTap ловит тап по одному из уведомлений этого приложения: пока приложение работает, и тап, который запустил приложение, — тот доставляется первому обработчику сразу после кода, который его подключил, так что обработчик на верхнем уровне приложения может сам выбрать экран. Открывай экран по data или url сам: url уведомления не приходит ни как app.launchUrl, ни событием "url".

TypeScript
Router.init(home)

notifications.onTap(tap => {                 // сюда попадает и холодный старт — после того как эта строка выполнилась
  if (tap.url) openURL(tap.url)              // или выбери экран: Router.push(screenFor(tap.url))
  else if (tap.id === 'weekly-review') Router.push(review)
})
  • Один обработчик на задачу; close() у возвращённой подписки его останавливает.
  • Тап ловится один раз: обработчик, подключённый позже, не услышит тап, который запустил приложение.

Отменить и посмотреть список: cancel, cancelAll, pending

TypeScript
notifications.cancel(id: string): void                  // ожидающее; если уже показано — убирает его из шторки
notifications.cancelAll(): void                         // все уведомления этого приложения
notifications.pending(): Promise<PendingNotification[]> // ещё не сработавшие; у повторяющегося — его следующее время

interface PendingNotification extends NotificationTap { at: number, repeat?: 'daily' | 'weekly' }
TypeScript
const stopReminding = () => notifications.cancel('water')

const showReminders = async () => {
  const list = await notifications.pending()
  rows.setContent(list.map(n => UIText(`${n.title} — ${date(n.at).format('D MMM HH:mm')}`)))
}

Разрешение

Спрашивает первый schedule. Чтобы спросить раньше — экран настроек с переключателем — или прочитать состояние, используй вид "notifications" у разрешений: permissions.query('notifications') без диалога отвечает 'granted', 'denied' или 'prompt', permissions.request('notifications') показывает диалог. За удалёнными push стоит то же разрешение ОС: выданное один раз, оно покрывает оба.

TypeScript
const row = UIRow()
const refresh = async () => {
  const state = await permissions.query('notifications')
  row.setContent([state === 'granted'
    ? UIText('Reminders are on')
    : UIButton(UIText('Turn reminders on')).onClick(async () => {
        const after = await permissions.request('notifications')
        if (after === 'denied') permissions.openSettings()   // iOS спрашивает один раз; Android — когда сам решит
        refresh()
      })])
}
app.addEventListener('resume', refresh)                      // вернулись из настроек
refresh()
  • iOS показывает диалог один раз; после отказа включить можно только в «Настройках». На Android 13+ такой же диалог; до 13 его нет, и состояние — переключатель уведомлений приложения.
  • Во вьюере le.codes разрешение — вьюера, общее для всех проектов, которые он запускает.

Смотрите также