Skip to content

Schedule Notification Flow

Jump to bottom
jjoonleo edited this page Jun 26, 2026 · 1 revision

Schedule Notification Flow

This page records the platform-specific schedule delivery flow for OnTime. The product language is intentional:

  • Notification means the user is alerted through an OS notification.
  • Alarm means OnTime can present a stronger alarm experience without the user first tapping a notification.
  • Android currently uses notification-based schedule delivery.
  • iOS uses alarm language only when AlarmKit is available and authorized.

Android Flow

Android separates notification display permission from exact timing permission. Users may still receive schedule notifications when exact timing is denied, but delivery is approximate.

flowchart TD
    A["Install or sign in"] --> B["Request notification permission"]
    B --> C{"Notification permission granted?"}
    C -- "No" --> D["Block schedule delivery\nStatus: Notification permission needed"]
    C -- "Yes" --> E["Request exact timing permission\nExplain: needed to notify at the exact preparation time"]
    E --> F{"Exact timing permission granted?"}
    F -- "Yes" --> G["Schedule with Android exact timing\nUser copy: Schedule notifications\nStatus: Precise notification"]
    F -- "No or later" --> H["Keep notification delivery enabled\nUse regular notification fallback\nStatus: Notification"]
    G --> I{"Upcoming schedule notification armed?"}
    H --> I
    I -- "Yes" --> J["Notify user at preparation time\nTap opens preparation flow"]
    I -- "No" --> K["Status: No scheduled notifications"]
Loading

iOS Flow

iOS is capability-aware. Alarm language is correct only when AlarmKit can be used for the current device and build. Otherwise, OnTime uses notification language.

flowchart TD
    A["Install or sign in"] --> B{"AlarmKit available\nfor this device and build?"}
    B -- "Yes" --> C["Request AlarmKit authorization\nUser copy: Allow alarms"]
    C --> D{"AlarmKit authorized?"}
    D -- "Yes" --> E["Schedule iOS AlarmKit alarm\nUser copy: Schedule alarm\nStatus: Alarm"]
    D -- "No or later" --> F["Request notification permission\nUser copy: Allow notifications"]
    B -- "No" --> F
    F --> G{"Notification permission granted?"}
    G -- "No" --> H["Block schedule delivery\nStatus: Notification permission needed"]
    G -- "Yes" --> I["Schedule local notification delivery\nUser copy: Schedule notifications\nStatus: Notification"]
    E --> J{"Upcoming delivery armed?"}
    I --> J
    J -- "Yes" --> K["Alarm or notification opens preparation flow"]
    J -- "No" --> L["Status: No scheduled notifications"]
Loading

Profile Status Labels

Platform / capability state User-facing status
Android exact timing armed Precise notification
Android notification fallback armed Notification
iOS AlarmKit armed Alarm
iOS notification fallback armed Notification
Notification permission missing Notification permission needed
No upcoming delivery armed No scheduled notifications
User disabled schedule delivery Off

Copy Rules

  • Android permission prompts should say notification, not alarm.
  • Android exact timing copy should explain why the extra permission exists: OnTime needs it to notify the user at the exact time to start preparing.
  • iOS prompts may say alarm only when requesting AlarmKit authorization.
  • Empty states should stay platform-neutral: No scheduled notifications.

Source Of Truth

  • Domain language: CONTEXT.md
  • Android decision: docs/adr/0008-use-notification-based-schedule-delivery-on-android.md
  • iOS decision: docs/adr/0009-use-alarm-language-only-for-ios-alarmkit.md
  • Permission gate: lib/presentation/app/cubit/alarm_gate_cubit.dart
  • Startup allow screen: lib/presentation/alarm_allow/screens/alarm_allow_screen.dart
  • Profile status: lib/presentation/my_page/my_page_screen.dart

Clone this wiki locally