Локальные уведомления и напоминания

1Что это добавляет#

Ваше приложение может показывать уведомления Android из собственного кода — на двух уровнях:

• Мгновенные (уровень 1): уведомление, которое появляется прямо сейчас, пока приложение открыто. Подходит для «загрузка завершена», «таймер сработал» и т. п.

• Запланированные напоминания (уровень 2): уведомление, которое срабатывает в заданное время, даже когда приложение ЗАКРЫТО, и переживает перезагрузку. Именно это нужно приложениям-напоминалкам, трекерам привычек, будильникам и приложениям для приёма лекарств.

Всё это работает на 100% на устройстве и офлайн — без сервера и аккаунта OneSignal. (Push OneSignal — отдельная функция для сообщений, которые ВЫ отправляете с сервера.)

2Включите это в мастере сборки#

На шаге 4 (Доступ) отметьте:

• 🔔 Уведомления — позволяют приложению показывать уведомления (добавляют POST_NOTIFICATIONS).
• ⏰ Напоминания — добавляют запланированные уведомления, которые срабатывают при закрытом приложении (добавляют точные будильники и перепланирование после перезагрузки). Если отметить «Напоминания», «Уведомления» включатся автоматически.

Оставьте оба пункта выключенными для приложений, которым уведомления не нужны, — в ваш APK ничего лишнего не добавится.

3Вызовите мост из вашего веб-кода#

AppMint предоставляет JavaScript-мост window.WebToApk. Всегда сначала проверяйте его наличие — он существует только в установленном приложении, поэтому ваш сайт по-прежнему работает в браузере.

const b = window.WebToApk || null;

// Ask once (Android 13+):
b?.requestNotificationPermission();

// Tier 1 — instant (app open):
b?.showNotification('Saved', 'Your note was saved', '', 'note');

// Tier 2 — scheduled reminder in 1 hour:
b?.scheduleNotification(
  'water-1',
  'Drink water',
  'Time for a glass of water',
  String(Date.now() + 60*60*1000),
  'daily'   // none | minutely | hourly | daily | weekly
);

b?.cancelNotification('water-1');
b?.cancelAllNotifications();
const pending = JSON.parse(b?.getScheduledNotifications() || '[]');

4Пусть ИИ подключит это за вас#

В AI App Studio просто опишите, что вам нужно, например: «напоминание о воде, которое пингует меня каждые 2 часа» или «трекер лекарств, который напоминает мне каждый день в 8 утра». Когда ваш запрос упоминает напоминания, будильники или уведомления, AppMint автоматически рассказывает ИИ об этом мосте, чтобы созданное приложение использовало его правильно (с мягким запасным вариантом, если он недоступен).

5Ваш собственный звук вместо стандартного звука Android#

Положите аудиофайл в веб-пакет (mp3, wav, ogg, m4a, flac или opus) и укажите путь к нему как звук. Это одинаково работает и для мгновенного уведомления, и для напоминания, которое сработает через несколько дней при закрытом приложении.

Файл копируется на место при планировании, поэтому неверное имя файла сразу вернёт false, а не превратится в стандартный звук в 7 утра.

Одно правило Android, которое стоит знать: звук канала уведомлений фиксируется при создании канала, поэтому AppMint создаёт отдельный канал для каждого звука. Из-за этого смена звука сбрасывает собственные настройки этого канала на экране уведомлений Android — это неизбежно и честно.

const b = window.WebToApk || null;

// Instant, with your sound:
b?.notify(JSON.stringify({
  title: 'Order confirmed',
  body:  'Arriving Tuesday',
  sound: '/audio/chime.mp3'   // a file in YOUR bundle
}));

// Check a sound before you save it in a settings screen:
const ok = b?.prepareNotificationSound('/audio/chime.mp3');

// 'silent' for no sound at all; leave it out for the Android default.

6Напоминания со звуком, картинками и кнопками#

scheduleNotificationEx() принимает всё то же, что и notify(), плюс время срабатывания. Используйте его вместо старого scheduleNotification() с пятью аргументами, когда нужно что-то большее, чем заголовок и текст.

const b = window.WebToApk || null;

b?.scheduleNotificationEx('dose-1', JSON.stringify({
  at: Date.now() + 60*60*1000,  // epoch millis
  repeat: 'daily',              // none|minutely|hourly|daily|weekly
  title: 'Time for your dose',
  body: 'Vitamin D — 1 tablet',
  sound: '/audio/chime.mp3',
  actions: [{ id: 'taken', label: 'Taken' }]
}));

// Returns false if the sound file does not exist — check it.

7Открытие самого приложения в заданное время#

Добавьте openApp: true — и напоминание станет полноэкранным оповещением: на заблокированном телефоне приложение откроется поверх экрана блокировки, на разблокированном появится как всплывающий баннер.

Это всё, что разрешает Android. Приложение не может тихо запустить себя в фоне — это заблокировано начиная с Android 10, — поэтому любая страница, обещающая «приложение просто откроется в 7 утра», должна работать через этот механизм. В Android 14+ пользователь разрешает такое оповещение для каждого приложения отдельно; проверьте canOpenAppAtTime() и, если ответ «denied», отправьте пользователя на экран настроек.

Когда приложение открывается так, ваша страница получает событие appmint:reminder, чтобы выполнить работу, которую не могла сделать, пока приложение было закрыто.

const b = window.WebToApk || null;

if (b?.canOpenAppAtTime() === 'denied') b?.requestOpenAppPermission();

b?.scheduleNotificationEx('standup', JSON.stringify({
  at: tomorrowAt9am, repeat: 'daily',
  title: 'Stand-up', body: 'Daily sync starts now',
  sound: '/audio/alarm.mp3',
  openApp: true
}));

window.addEventListener('appmint:reminder', e => {
  // e.detail = { id: 'standup', overLockScreen: true }
  showReminderScreen(e.detail.id);
});

8Надёжность на реальных устройствах#

Запланированные напоминания работают настолько надёжно, насколько это позволяет Android:

• В Android 12+ для точного времени нужно разрешение SCHEDULE_EXACT_ALARM. Если оно выключено для вашего приложения, напоминание ставится в окно 10 минут (позже, пока телефон спит), и приложение один раз объясняет это пользователю. Спросите getAlarmPrecision() — он отвечает 'exact' или 'inexact' — и вызовите requestExactAlarms(), чтобы отправить пользователя к настройке. Приложение-будильник или календарь может отметить в мастере «My app is an alarm clock or calendar app»: тогда точные будильники всегда включены (Google Play требует декларацию Exact alarm в Play Console).
• Некоторые телефоны (Xiaomi, Samsung, Oppo и др.) задерживают или останавливают фоновые будильники ради экономии заряда. Приложение один раз объясняет это (с путём к «Ограничениям фонового использования» у Samsung) и открывает список оптимизации батареи.
• Напоминания автоматически ставятся заново после перезагрузки телефона или обновления приложения.

9Верните пользователей, которые отключили уведомления#

Многие нажимают «Не разрешать» в запросе на уведомления в Android 13 или пропускают его, а Android показывает этот запрос лишь ограниченное число раз. После этого включить уведомления можно только в настройках уведомлений приложения.

AppMint.enableNotifications() делает правильное действие по нажатию кнопки пользователем: показывает запрос разрешения, пока Android ещё может его показать, а иначе открывает настройки уведомлений приложения — и сообщает новое состояние, когда пользователь возвращается. getNotificationState() отвечает 'granted', 'prompt' (можно ещё спросить), 'blocked' (исправить может только «Настройки») или 'unavailable' (в сборке нет уведомлений). Показывайте свой баннер только для 'prompt' и 'blocked' и никогда не спрашивайте при запуске.

Кнопка в push- или внутриигровом сообщении со ссылкой appmint://notifications/enable делает то же самое без какого-либо кода на странице.

const A = window.AppMint;
if (A?.enableNotifications) {
  const state = await A.getNotificationState();
  // 'granted' | 'prompt' | 'blocked' | 'unavailable'
  banner.hidden = !(state === 'prompt' || state === 'blocked');

  turnOnButton.onclick = async () => {
    const r = await A.enableNotifications();
    // r = { state, changed, openedSettings }
    banner.hidden = r.state === 'granted';
  };
}

// Just the settings screen:
A?.openNotificationSettings?.();