Уведомления
notifications планирует уведомление на самом устройстве — напоминание на время, ежедневное или
показанное прямо сейчас — и ловит тап по нему. Сервер не участвует: уведомление, которое твой
бэкенд отправляет пользователю, — дело плагина push (Push). Запланированное
уведомление устройство показывает и при закрытом приложении; тап открывает приложение и доходит до
onTap.
- напомнить пользователю в выбранное им время (лекарство, тренировка, дедлайн)
- ежедневное или еженедельное напоминание в одно и то же время
- показать уведомление прямо сейчас (загрузка завершилась, твой ход в игре)
- открыть нужный экран, когда пользователь тапнул по уведомлению, в том числе если тап запустил приложение
- отменить напоминание или посмотреть список ещё не сработавших
- запросить разрешение на уведомления раньше или обработать отказ
Платформы: iOS и Android. На десктопе, в вебе и в headless-тестах их нет:
notifications.supported равен false, schedule отклоняется, остальное ничего не делает.
Обзор
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
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: задай свой,
если потом будешь заменять или отменять уведомление (одно напоминание на лекарство, по ключу
лекарства), или возьми сгенерированный.
// показать сейчас
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
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".
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
notifications.cancel(id: string): void // ожидающее; если уже показано — убирает его из шторки
notifications.cancelAll(): void // все уведомления этого приложения
notifications.pending(): Promise<PendingNotification[]> // ещё не сработавшие; у повторяющегося — его следующее время
interface PendingNotification extends NotificationTap { at: number, repeat?: 'daily' | 'weekly' }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 стоит то же разрешение
ОС: выданное один раз, оно покрывает оба.
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 разрешение — вьюера, общее для всех проектов, которые он запускает.
Смотрите также
- Разрешения —
query,request,openSettings - Push — уведомления, отправленные с твоего сервера
- Жизненный цикл приложения —
"resume",app.launchUrl(егоurlуведомления не использует) - Даты —
date()для времени, которое ты планируешь и показываешь