DEV Community: Mxolisi Masuku

Build Reliable Local Notifications in Flutter (Step-by-Step)

Mxolisi Masuku — Thu, 16 Apr 2026 08:43:51 +0000

Companion post to How I Built the Long Game Notification System. This is the walkthrough. If you want the thinking behind the decisions, read that first. If you just want the recipe, you're in the right place.

What You're Building

A notification system where:

Notifications fire at the exact time you set, every day
They work when the phone is locked, the app is killed, or the device is in Doze mode
Notification content is personalized with fresh data on every app open
The entire system runs locally — no push server, no Cloud Functions, zero delivery cost
Pomodoro-style one-shot alarms fire on time even when the app is suspended
Notifications survive Samsung, Xiaomi, and Huawei battery killers without FCM

What You're NOT Using

workmanager — the OS throttles background tasks. Your 15-minute poll becomes hours.
Dart Timer.periodic for delivery — dies the moment the phone locks.
Firebase Cloud Messaging — overkill for local, user-specific scheduling.
Background Fetch (iOS) — Apple gives you 0–2 executions per day if you're lucky.

Step 1: Dependencies

# pubspec.yaml
dependencies:
  flutter_local_notifications: ^18.0.1
  timezone: ^0.10.0
  flutter_timezone: ^3.0.1
  permission_handler: ^11.3.1

That's it. Four packages.

The notification plugin handles scheduling.
The timezone packages ensure your 8:00 AM means 8:00 AM in Johannesburg, not UTC.
The permission handler lets you request notification access on Android 13+ and battery optimization exemption on Samsung/OEM devices.

Step 2: Android Permissions

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
<uses-permission android:name="android.permission.USE_EXACT_ALARM" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

What each one does:

Permission	Why
`POST_NOTIFICATIONS`	Required on Android 13+ to show any notification at all
`RECEIVE_BOOT_COMPLETED`	Alarms survive device reboots
`SCHEDULE_EXACT_ALARM`	Fires at the exact second, even in Doze mode (API ≤ 33)
`USE_EXACT_ALARM`	Guaranteed exact alarms on API 33+ — no user prompt needed, unlike `SCHEDULE_EXACT_ALARM` on API 34+
`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`	Lets you show the system "Allow unrestricted battery?" dialog — critical for Samsung, Xiaomi, Huawei
`WAKE_LOCK`	Keeps the CPU alive long enough to process the alarm and fire the notification

Watch out: On Android 14+ (API 34), SCHEDULE_EXACT_ALARM isn't granted by default. USE_EXACT_ALARM is a stronger alternative that's always granted for apps that declare it — but it may trigger Google Play review. Having both ensures maximum compatibility. Your code still needs the inexact fallback we'll cover in Step 7.

Step 3: Initialize on App Start

Before you can schedule anything, you need to initialize the timezone database and the notification plugin. This runs once in main(), before runApp().

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // ... your other init code (Firebase, etc.)

  await NotificationService.init();
  runApp(const MyApp());
}

// notification_service.dart
import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:timezone/timezone.dart' as tz;
import 'package:timezone/data/latest_all.dart' as tzdata;
import 'package:flutter_timezone/flutter_timezone.dart';
import 'package:permission_handler/permission_handler.dart';

class NotificationService {
  static final FlutterLocalNotificationsPlugin _plugin =
      FlutterLocalNotificationsPlugin();

  static Future<void> init() async {
    // 1. Initialize the timezone database and detect the device's zone.
    //    Without this, all scheduled times are wrong.
    tzdata.initializeTimeZones();
    try {
      final tzName = await FlutterTimezone.getLocalTimezone();
      tz.setLocalLocation(tz.getLocation(tzName));
    } catch (_) {
      // Fallback: stays UTC if detection fails
    }

    // 2. Initialize the plugin.
    //    We don't request permissions here — that happens later,
    //    at a moment that makes sense in your UX flow.
    const androidSettings = AndroidInitializationSettings(
      '@mipmap/ic_launcher',
    );
    const iosSettings = DarwinInitializationSettings(
      requestAlertPermission: false,
      requestBadgePermission: false,
      requestSoundPermission: false,
    );

    await _plugin.initialize(
      const InitializationSettings(
        android: androidSettings,
        iOS: iosSettings,
      ),
      onDidReceiveNotificationResponse: _onNotificationTap,
      onDidReceiveBackgroundNotificationResponse: _onBackgroundTap,
    );
  }

  // Handle taps when the app is alive
  static void _onNotificationTap(NotificationResponse response) {
    // Navigate to the relevant screen, stop a timer, etc.
  }

  // Handle taps when the app was killed — must be top-level or static
  @pragma('vm:entry-point')
  static void _onBackgroundTap(NotificationResponse response) {
    // App relaunches — handle in your normal init flow
  }
}

Why timezone matters: If you schedule for "8:00 AM" without initializing timezones, the plugin may interpret that as UTC. In Johannesburg (UTC+2), that's 10:00 AM. In New York (UTC-5), that's 3:00 AM. Always initialize before any zonedSchedule call.

Step 4: Schedule a Daily Repeating Notification

This is the core of the entire system. Three lines do the heavy lifting.

static Future<void> scheduleDailyNotification({
  required int id,
  required String title,
  required String body,
  required int hour,
  required int minute,
}) async {
  await _plugin.zonedSchedule(
    id,                                           // Fixed ID per notification type
    title,
    body,
    _nextInstanceOfTime(hour, minute),            // Next occurrence of this time
    const NotificationDetails(
      android: AndroidNotificationDetails(
        'your_channel_id',
        'Your Channel Name',
        channelDescription: 'What this channel is for',
        importance: Importance.high,
        priority: Priority.high,
      ),
      iOS: DarwinNotificationDetails(),
    ),
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    matchDateTimeComponents: DateTimeComponents.time,    // ← THIS IS THE KEY
  );
}

The three things that make it work:

exactAllowWhileIdle — fires even in Doze mode. The OS wakes up just enough to deliver your notification.
matchDateTimeComponents: DateTimeComponents.time — tells the OS: "repeat this every day at this hour:minute." You schedule it once. It fires every day. No background task. No polling.
_nextInstanceOfTime — computes the next future occurrence of the target time.

static tz.TZDateTime _nextInstanceOfTime(int hour, int minute) {
  final now = tz.TZDateTime.now(tz.local);
  var scheduled = tz.TZDateTime(
    tz.local,
    now.year,
    now.month,
    now.day,
    hour,
    minute,
  );
  // zonedSchedule requires a future datetime
  if (scheduled.isBefore(now)) {
    scheduled = scheduled.add(const Duration(days: 1));
  }
  return scheduled;
}

Why this helper exists: zonedSchedule requires the initial fire time to be in the future. If it's 9:00 AM and you schedule for 8:00 AM, the helper pushes it to 8:00 AM tomorrow. The matchDateTimeComponents flag handles every day after that.

Step 5: CRITICAL: The Cancel Trap

==(This bit is annoying if not taken care of)==

This is the bug that will silently break your notifications and you won't notice for days. I shipped it. It cost me a full day of missed notifications before I caught it.

The broken pattern

//  DO NOT DO THIS
static Future<void> reschedule() async {
  await _plugin.cancel(id);                     // Destroys the repeating alarm
  await _plugin.zonedSchedule(id, ...);         // Creates a new one
}

It looks correct. It's not. Here's what happens:

User opens the app at 9:00 AM
cancel(1) — destroys the existing repeating 8:00 AM alarm
_nextInstanceOfTime(8, 0) — 8:00 AM today already passed, returns tomorrow 8:00 AM
zonedSchedule(1, ...) — schedules a new alarm starting tomorrow
Tomorrow, user opens the app at 9:00 AM again → same thing
The notification is perpetually pushed to "tomorrow" and never fires

The correct pattern

// Only cancel when the user disables the notification
static Future<void> schedule(bool enabled, int hour, int minute) async {
  if (!enabled) {
    await _plugin.cancel(id);    // User turned it off — remove the alarm
    return;
  }
  // Calling zonedSchedule with the same ID REPLACES the existing alarm
  // without resetting the repeat cycle. No cancel needed.
  await _plugin.zonedSchedule(id, ...);
}

The rule: zonedSchedule with the same ID overwrites the previous alarm — it updates the title, body, and schedule time without destroying the repeat. You only need cancel when you want the notification to stop entirely.

This means you can safely call rescheduleAll() on every app open to refresh notification content (e.g., "You have 3 projects today" becomes "You have 4 projects today") without breaking delivery.

Step 6: Refresh Content on App Open

Notification bodies are frozen at schedule time. If the user adds a project at 11 PM, you want tomorrow's morning notification to include it.

// main.dart — after init, before runApp
if (FirebaseAuth.instance.currentUser != null) {
  NotificationService.rescheduleAllNotifications().catchError((_) {});
}

rescheduleAllNotifications() fetches fresh data and calls zonedSchedule for each enabled notification, overwriting the stale body. No cancel — just overwrite.

Two things to guard against:

Auth check — if your notification content depends on user-specific data (Firestore queries), and no user is signed in, the query will hang. This blocks main() and your app never starts. Gate it.
Fire-and-forget — use .catchError((_) {}). If the reschedule fails (offline, Firestore timeout), the previously scheduled alarm still fires with yesterday's content. That's better than crashing on startup.

Step 7: Handle Android 14+ Exact Alarm Restriction

Android 14 changed the rules. SCHEDULE_EXACT_ALARM is no longer auto-granted. If your app calls exactAllowWhileIdle without the permission, it throws.

The graceful fallback:

static Future<void> scheduleDailyNotification({
  required int id,
  required String title,
  required String body,
  required int hour,
  required int minute,
}) async {
  final scheduledTime = _nextInstanceOfTime(hour, minute);
  final details = /* your NotificationDetails */;

  try {
    // Try exact first — best experience
    await _plugin.zonedSchedule(
      id, title, body, scheduledTime, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
      matchDateTimeComponents: DateTimeComponents.time,
    );
  } catch (e) {
    // Exact alarm not permitted — fall back to inexact
    // Delivery may drift by ~10 minutes, but the notification still fires
    await _plugin.zonedSchedule(
      id, title, body, scheduledTime, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
      matchDateTimeComponents: DateTimeComponents.time,
    );
  }
}

For most notifications, a 10-minute window is fine. "Your day is 63% gone" at 2:10 PM instead of 2:00 PM doesn't break the experience.

Apply this same pattern to one-shot alarms too. Your pomodoro alarm scheduler should have the same try/catch:

static Future<void> schedulePhaseAlarm({
  required int durationMinutes,
  required NotificationDetails details,
}) async {
  final fireAt = tz.TZDateTime.now(tz.local)
      .add(Duration(minutes: durationMinutes));

  try {
    await _plugin.zonedSchedule(
      alarmId, title, message, fireAt, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    );
  } catch (_) {
    // Fall back to inexact — still fires, may drift ~5-10 min
    try {
      await _plugin.zonedSchedule(
        alarmId, title, message, fireAt, details,
        uiLocalNotificationDateInterpretation:
            UILocalNotificationDateInterpretation.absoluteTime,
        androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
      );
    } catch (e) {
      print('[Notifications] Failed to schedule alarm: $e');
    }
  }
}

Step 8: One-Shot Alarms (Pomodoro, Timers)

Daily repeating alarms cover most cases. But sometimes you need a notification that fires once at a specific future time — like when a 25-minute pomodoro focus session ends.

static Future<void> scheduleOneShot({
  required int id,
  required String title,
  required String body,
  required int minutesFromNow,
  required NotificationDetails details,
}) async {
  final fireAt = tz.TZDateTime.now(tz.local)
      .add(Duration(minutes: minutesFromNow));

  await _plugin.zonedSchedule(
    id,
    title,
    body,
    fireAt,
    details,
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    // NO matchDateTimeComponents — this fires once, doesn't repeat
  );
}

Why you need this for pomodoro: A Dart Timer.periodic runs in your app's process. When the user locks their phone, the OS suspends the app within ~30 seconds. Your timer stops ticking. The phase ends, and — silence. The bell only rings when they unlock the phone and the app resumes.

An OS alarm doesn't care about your app's lifecycle. It fires regardless.

Making one-shot alarms alarm-grade

A standard Importance.high notification won't cut it on Samsung, Xiaomi, or Huawei devices. These OEMs aggressively kill background processes and suppress notifications they deem non-essential. You need to make your notification look like an alarm clock to the OS:

import 'dart:typed_data';

NotificationDetails _alarmGradeDetails({required bool isWorkPhase}) {
  final soundFile = isWorkPhase ? 'bell_focus' : 'bell_break';
  final channelId = isWorkPhase ? 'focus_bell' : 'break_bell';
  final channelName = isWorkPhase ? 'Focus Bell' : 'Break Bell';

  return NotificationDetails(
    android: AndroidNotificationDetails(
      channelId,
      channelName,
      channelDescription: 'Pomodoro phase transition',
      importance: Importance.max,                              // Maximum priority
      priority: Priority.max,
      sound: RawResourceAndroidNotificationSound(soundFile),
      playSound: true,
      fullScreenIntent: true,                                  // Wakes the screen
      category: AndroidNotificationCategory.alarm,             // Treated like an alarm
      visibility: NotificationVisibility.public,               // Shows on lock screen
      enableVibration: true,
      vibrationPattern: Int64List.fromList([0, 400, 200, 400]),
    ),
    iOS: DarwinNotificationDetails(
      presentAlert: true,
      presentSound: true,
      sound: '$soundFile.wav',
      interruptionLevel: InterruptionLevel.timeSensitive,      // Breaks through Focus
    ),
  );
}

What each flag does:

Flag	Effect
`importance: Importance.max`	Heads-up notification — appears at the top of the screen
`fullScreenIntent: true`	Wakes the screen and shows the notification even when locked. This is what alarm clock apps use.
`category: AndroidNotificationCategory.alarm`	Tells the OS this is time-critical. Samsung's battery manager respects this category.
`visibility: NotificationVisibility.public`	Content visible on the lock screen without unlocking
`vibrationPattern`	Custom vibration so the user physically feels it
`interruptionLevel: InterruptionLevel.timeSensitive`	iOS 15+: breaks through Focus mode

This is the difference between a notification that works on your desk and one that works in your pocket. Standard Importance.high gets silently suppressed by Samsung's battery manager. Importance.max + fullScreenIntent + category: alarm does not.

The dual-delivery pattern

When the app is in the foreground, the Dart timer catches the transition first (instant feedback). When the phone is locked, the OS alarm delivers it. To avoid the user hearing two bells:

// In your timer tick (foreground path)
void _onPomodoroPhaseEnd() {
  _plugin.cancel(alarmId);            // Cancel the OS alarm (Dart beat it)
  _plugin.show(displayId, ...);       // Show the notification immediately
  _scheduleNextPhaseAlarm();          // Schedule for the next phase
}

Use separate IDs for the scheduled alarm and the instant notification if you want, or the same ID if you want one to replace the other. Either way, the user sees exactly one notification.

Step 9: Weekly Repeating Notifications

For notifications that fire on specific weekdays — like a project reminder every Monday, Wednesday, and Friday at 6:00 PM.

static Future<void> scheduleWeekly({
  required int id,
  required String title,
  required String body,
  required int weekday,    // 1 = Monday, 7 = Sunday
  required int hour,
  required int minute,
}) async {
  await _plugin.zonedSchedule(
    id,
    title,
    body,
    _nextInstanceOfWeekdayTime(weekday, hour, minute),
    /* notificationDetails */,
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
    matchDateTimeComponents: DateTimeComponents.dayOfWeekAndTime,  // ← Weekly
  );
}

static tz.TZDateTime _nextInstanceOfWeekdayTime(
  int weekday, int hour, int minute,
) {
  final now = tz.TZDateTime.now(tz.local);
  var scheduled = tz.TZDateTime(
    tz.local, now.year, now.month, now.day, hour, minute,
  );
  // Advance to the target weekday
  while (scheduled.weekday != weekday) {
    scheduled = scheduled.add(const Duration(days: 1));
  }
  // If it's already passed this week, push to next week
  if (scheduled.isBefore(now)) {
    scheduled = scheduled.add(const Duration(days: 7));
  }
  return scheduled;
}

Important: Each weekday needs its own notification ID. If you want reminders on Monday, Wednesday, and Friday, that's three separate zonedSchedule calls with three different IDs. When removing the reminder, cancel all of them.

// Generating unique IDs per project + weekday
final notifId = baseId + projectId.hashCode.abs() % 900 + weekday;

Step 10: Surviving Samsung Battery Optimization

This is the step most Flutter notification tutorials skip, and it's why your notifications work perfectly during development but fail silently in production.

The problem

Samsung, Xiaomi, Huawei, OnePlus, and most Chinese OEMs add an aggressive battery optimization layer on top of Android's standard Doze mode. Even if your alarm is correctly scheduled with exactAllowWhileIdle, the OEM's battery manager can:

Kill your app process after ~5 minutes of screen-off time
Block AlarmManager exact alarms from waking the app
Silently suppress notifications from "sleeping" apps

This is why WhatsApp, Duolingo, and Telegram work but your app doesn't — Google Play Services (which delivers FCM push notifications) is whitelisted at the system level. Your app is not. You need the user to manually exempt you.

The solution

Android provides a system dialog that asks the user to whitelist your app from battery optimization. You can trigger it using the permission_handler package (which you already have for notification permissions):

import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:shared_preferences/shared_preferences.dart';

class BatteryOptimizationService {
  static const String _keyAsked = 'battery_optimization_asked';

  /// Check if the app is already exempted from battery optimizations.
  static Future<bool> isExempted() async {
    if (!Platform.isAndroid) return true;
    final status = await Permission.ignoreBatteryOptimizations.status;
    return status.isGranted;
  }

  /// Request battery optimization exemption.
  /// Shows the system "Allow unrestricted battery?" dialog.
  static Future<bool> requestExemption() async {
    if (!Platform.isAndroid) return true;
    final status = await Permission.ignoreBatteryOptimizations.request();
    return status.isGranted;
  }

  /// Check and prompt once — call on first pomodoro start.
  static Future<void> ensureExemptedForPomodoro() async {
    if (!Platform.isAndroid) return;
    if (await isExempted()) return;

    final prefs = await SharedPreferences.getInstance();
    if (prefs.getBool(_keyAsked) ?? false) return;

    final granted = await requestExemption();
    await prefs.setBool(_keyAsked, true);
    debugPrint('[Battery] Exemption ${granted ? "granted" : "denied"}');
  }
}

When to prompt

Don't ask on app first launch — the user has no context for why you need it. Ask at the moment it matters:

Future<void> startPomodoro(String projectId, {required String projectName}) async {
  // Ask BEFORE the timer starts — user understands why
  await BatteryOptimizationService.ensureExemptedForPomodoro();

  // ... start the timer, schedule the alarm
}

The system dialog is native Android UI — it looks official, not spammy. And because we gate it with _keyAsked, the user only sees it once.

What the user sees

The dialog says something like:

Let LongGame run in the background?

This app will be able to run in the background, which may increase battery usage.

[DENY] [ALLOW]

If they tap "Allow", your app is exempted from the OEM's battery killing. Your exactAllowWhileIdle alarms now fire reliably even with the screen off.

For extra reliability

If your users are on Samsung specifically, you may also want to link them to the device-specific battery settings. Samsung has an additional "Sleeping Apps" list that operates independently of Android's standard battery optimization. The don't kill my app project maintains device-specific instructions you can reference in your settings screen.

Step 11: Custom Notification Sounds

If you want distinct sounds for different notification types — like a bright bell for "focus" and a warm chime for "break" — you need three things.

File placement

android/app/src/main/res/raw/bell_focus.wav     ← Android reads from res/raw
ios/Runner/bell_focus.wav                        ← iOS reads from app bundle
assets/sounds/bell_focus.wav                     ← Optional: Flutter assets

Notification details with sound

NotificationDetails(
  android: AndroidNotificationDetails(
    'channel_focus_bell',                                    // Unique channel ID
    'Focus Bell',
    sound: RawResourceAndroidNotificationSound('bell_focus'), // No file extension
    playSound: true,
  ),
  iOS: DarwinNotificationDetails(
    presentSound: true,
    sound: 'bell_focus.wav',                                  // With file extension
  ),
);

The channel rule

Android requires a separate notification channel for each distinct sound. Once a channel is created, its sound cannot be changed programmatically — the user would need to clear app data or reinstall. Name your channels carefully the first time.

// One channel per sound
'longgame_focus_bell'   →  bell_focus.wav
'longgame_break_bell'   →  bell_break.wav
'longgame_reminders'    →  default system sound

// Don't try to reuse a channel with different sounds
// The first sound "wins" and the channel ignores subsequent changes

The Complete Reference

Which mechanism to use

Scenario	Method	Repeats?
Daily notification (8:00 AM every day)	`zonedSchedule` + `DateTimeComponents.time`	Every day
Weekly reminder (Mon at 6:00 PM)	`zonedSchedule` + `DateTimeComponents.dayOfWeekAndTime`	Every week
One-shot alarm (25 min from now)	`zonedSchedule`, no `matchDateTimeComponents`	Once
Persistent indicator (timer running)	`_plugin.show()` with `ongoing: true`	Until cancelled
Instant alert (event just happened)	`_plugin.show()`	Once

Which notification details to use

Scenario	Importance	fullScreenIntent	Category	Why
Daily nudge / reminder	`high`	`false`	—	Standard heads-up, doesn't need to wake the screen
Pomodoro phase transition	`max`	`true`	`alarm`	Must wake the screen and break through Samsung battery killing
Ongoing timer	`low`	`false`	`stopwatch`	Persistent but non-intrusive, lives in the notification shade
Session reminder	`high`	`false`	—	Standard importance, user is likely awake

What not to use

Approach	What goes wrong
`WorkManager` periodic task	OS throttles it. 15-minute minimum becomes hours in Doze.
`Dart Timer.periodic` for alerts	Stops when phone locks. App suspended = timer dead.
`cancel()` then `zonedSchedule()` on app open	Perpetually pushes alarm to "tomorrow." Never fires.
iOS Background Fetch	0–2 executions per day. Apple decides when, not you.
`Importance.high` for time-critical alarms	Samsung silently suppresses it. Use `max` + `alarm`.
Ignoring battery optimization	Works on Pixel, dies on Samsung. 70%+ of Android users are on OEM skins.

Android permissions checklist

Permission	When needed
`POST_NOTIFICATIONS`	Always (Android 13+)
`RECEIVE_BOOT_COMPLETED`	If alarms should survive reboots
`SCHEDULE_EXACT_ALARM`	Exact alarms (API ≤ 33, runtime request on API 34+)
`USE_EXACT_ALARM`	Guaranteed exact alarms (API 33+), no user prompt
`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`	Battery exemption dialog
`WAKE_LOCK`	Keep CPU alive during alarm processing

Notification IDs

Use fixed IDs per notification type. zonedSchedule with the same ID replaces the existing alarm. This is your friend — it's how you update content without breaking repeats.

static const int idMorningIntent = 1;
static const int idDriftAlert    = 2;
static const int idMirror        = 3;
static const int idStreak        = 4;
static const int idTimerRunning  = 5;
static const int idOngoingTimer  = 6;
static const int idPomodoroAlarm = 98;
static const int idPomodoro      = 99;
static const int idSessionBase   = 100;  // + project hash + weekday

The Bugs To Watch For

Bug 1: The startup hang

Your rescheduleAll() queries Firestore for personalized content. If no user is signed in, the Firestore SDK with offline persistence doesn't throw — it hangs. Your main() never reaches runApp(). The app is stuck on the splash screen.

Fix: Check FirebaseAuth.instance.currentUser != null before rescheduling. Also make the call fire-and-forget with .catchError() so a Firestore timeout doesn't block startup.

Bug 2: The cancel-reschedule cycle

Covered in Step 5, but worth repeating because it's the most insidious bug. It works perfectly in development (you're always testing right after scheduling), and fails silently in production (the user opens the app after the notification time, so it's always pushed to tomorrow).

Fix: Never cancel before zonedSchedule for enabled notifications. Only cancel when disabling.

Bug 3: The locked-phone silence

Your Dart timer works nicely in the foreground. You test it, the notification fires after 25 minutes, you ship. Then a user runs a pomodoro session, puts the phone down, and hears nothing. The OS suspended your app. Your timer stopped.

Fix: Schedule a one-shot OS alarm for the exact phase end time. The Dart timer is for foreground UX; the OS alarm is for reliability. Let them race.

Bug 4: The Samsung battery killer

Everything works on your Pixel. Every alarm fires on time. You ship. Then 70% of your users (Samsung, Xiaomi, Huawei) report that pomodoro notifications never arrive when the screen is off.

Samsung adds "Sleeping Apps" and "Deep Sleeping Apps" lists on top of Android's standard Doze. Even exactAllowWhileIdle alarms are suppressed for apps on these lists. Your perfectly scheduled alarm never fires because Samsung killed your process and blocked the AlarmManager wakeup.

Fix (three layers, use all of them):

Request battery optimization exemption — show the system "Allow unrestricted?" dialog on first pomodoro start. This removes you from the standard Android optimization. (Step 10)
Use alarm-grade notification details — fullScreenIntent: true + category: alarm + Importance.max. The OS treats these like alarm clock notifications and is far less likely to suppress them. (Step 8)
Declare USE_EXACT_ALARM — this permission is always granted on API 33+ without user interaction, giving you a stronger guarantee than SCHEDULE_EXACT_ALARM alone. (Step 2)

None of these alone is sufficient. Together, they give you the same delivery reliability as WhatsApp on Samsung.

The Cost

Component	Cost per user
FCM push messages	$0 — not used
Cloud Functions	$0 — computed on-device
Firestore reads for content	$0 — bundled with existing app queries
Local alarm scheduling	$0 — OS-level, no backend
Battery optimization prompt	$0 — native system dialog

The entire notification system runs at zero marginal cost. The trade-off is that notification content is only as fresh as the user's last app open. For daily reflections and nudges, that's perfectly fine — you're computing tomorrow's content with today's data, and it's accurate enough to be useful.

This is the system behind Long Game, a life auditing app for people who want to be intentional with their time. The original post explaining the design decisions is here.

The People On The Other Side Of Your Upwork Proposal

Mxolisi Masuku — Mon, 30 Mar 2026 03:19:47 +0000

Upwork is increasingly getting difficult — or so they say. I've had quite a number of friends who created an account and abandoned it, and others curious about whether it's worth starting. The conversation kept repeating itself so I decided to write this.

If the Internet tells you Upwork is a scam, understand what you are actually hearing: frustration from people who didn't make it, and silence from the thousands quietly building careers on the platform. People who are making money on Upwork eat quietly. The loudest voices are freelancers turned influencers who make money coaching you, and the disgruntled ones on Reddit whose complaints come wrapped in humble brags. "I have a $400k account but Upwork treated me like this." $400k is life-changing money — but if you break the rules, Upwork is judge, jury and executioner. Your account size doesn't matter.

The Numbers Behind The Noise

Upwork is not a startup hoping to find product-market fit. It is the dominant player in the freelance platform market.

Record full-year revenue of $788 million in 2025. Over $4 billion in gross services volume — that's the total amount clients spent on the platform in a single year. More than 18 million registered freelancers across 180+ countries. Around 800,000 active clients. Upwork holds roughly 61% of the freelance platform market share, more than triple Fiverr's and double Toptal's. Fast Company named them one of the Most Innovative Companies of 2025, and Frost & Sullivan gave them the Global New Product Innovation Award in 2023.

AI-related work on the platform grew 60% year-over-year in 2024, and freelancers working on AI projects earned 44% more per hour than those who didn't. The average freelancer hourly rate sits around $39. Web and software development accounts for 34% of all work on the platform.

Why does this matter to you? $4 Billion in circulation means this is not a dying marketplace. The money is real, the clients are real, and the opportunity is real. The question is whether you can position yourself to capture your slice of it.

1. Think People First

Before you get into the Upwork algorithm debate, start here: Who are the people on the other side of your proposals?

The client landscape has shifted. Three or four years ago, the typical Upwork client had money to spend, no time to look for talent, and needed an automated way to protect their interests. You saw people offering 3-year contracts at $40 an hour.

Since 2025, the attitude has changed. Everyone is looking to save. But not everyone is looking to save the same way. Here's how I break down the client tiers on Upwork right now:

The top-tier client understands the value of AI in speeding things up. He has money but is not willing to splash it on a slow freelancer. This client wants the best person on the job who can leverage AI to move fast, and can pay explosive amounts for it. Usually after the first successful job, these people will negotiate a long-term contract with a reliable freelancer. They don't sift through 150 proposals. They go to Upwork and say "find me someone who can do this" and the algorithm feeds them the best and boosted profiles. This is where Connects, profile optimisation and your Upwork ranking all come in.

The fair-price client says "I have this job, I have this amount, let's work." Expect fair treatment here. This kind of client appreciates honesty, communication and thoroughness. These are skills you should have or be actively improving.

The exploitative client knows the freelance labour market is full of desperate people right now. So he dangles a carrot. $50 for a hard job. Then he piles on responsibility knowing the developer will do it just to get good reviews. Upwork has documentation to help you handle this, but you need to recognise the pattern before you're already trapped.

The scammer. You have to beware of these. They will take you for everything you've got. Steal, use you, hack you or worse. Follow Upwork's guidelines on surviving scammers and go to the unofficial Upwork Reddit channel — r/Upwork. It's unhinged and town-square-like, but it will help you catch up fast with how scams are evolving.

Pro tip: Read The General Guide To Upwork Scams on Reddit

Once you know the people, you know who you need to become to be chosen. You can play the algorithm all you want, but on the other end of everything you type, there is a person who is as interested in gaining value and as afraid of losing money on bad product as you are.

Think people first. Upwork is a community brought together by the platform. The rules matter as much as the people they serve.

2. Play The Long Game But Work Hard On Your Short Plays

Freelancing is hard and competitive. Upwork, being the top platform, is even more competitive. Whether you are new or a seasoned freelancer looking to reinvent yourself: your patience will be tested and your persistence will be rewarded.

The long-term goal is being on a stable, well-paying contract. Being a top freelancer that Upwork recommends to its best clients. Getting paid consistently.

The mid-term goal is building up smaller, shorter contracts. Quick jobs. Building your skill set, networking, studying the market. You don't get to the long-term goal without passing through this one unless you are extremely lucky.

The immediate goal is your short plays. This is where the real work happens and where most freelancers give up too early.

In my experience, I got lucky in a sense — I got to Top Rated Plus with just 3 jobs. But those 3 jobs amount to 2,240+ hours. My takeaway: there is more value in sustaining a long-term business relationship than in chasing volume. Your mileage may vary, but there is no substitute for good work and maintaining good relationships.

As you improve your profile, think of every iteration of profile development as a play that must be analysed and improved. Every proposal is a data point that needs to be dissected and built on.

Source: r/Upwork

Look at this from r/Upwork. 49 proposals sent in 90 days. Only 7 were even viewed. 3 interviews. 2 hires. $1,500 earned in the first few months on the platform. This is what the grind looks like. Most of your proposals will disappear into the void. The game is making sure the ones that land are good enough to convert.

Read job posts. What skills are clients asking for? What's the overall application tone on key skills? It's all about patience, playing the long game and relentlessly looking to improve.

Right now, in most of the job posts I see, clients are prioritising freelancers who have an AI-first attitude. n8n, Agentic Workflows, Supabase, Firebase, Cursor, Antigravity top almost every post. These can be pointers but they can also get you panicking and chasing the wind. When you see trends like these you can either choose to be a generalist or a specialist. I chose to specialise. Depth beats breadth when a client scans 50 proposals and needs to trust that you've solved their exact problem before.

In the job posts, listen to what clients are saying about what they need. More importantly, listen to what they're saying about the freelancer they want to work with. Become that person.

Again. Think people first.

3. Follow The Rules

The most nerve-wracking moment in your Upwork journey will be right after a client says "Hey, I saw your proposal. I'm interested. Let's talk."

At this moment, your position must shift: DO NOT THINK PEOPLE FIRST. Think Upwork first.

Do not be hoodwinked. Your main concern shouldn't be what the other person is saying. It should be: what does Upwork say about this? For every response you send, you must consider the Upwork funnel and playbook.

Failure to do so will result in a ban. Back in the day the ban was effective immediately and non-negotiable, though this may be shifting since Upwork now shows you account health status.

Things to know: Upwork is ruthless on freelancers who share personal contact details before a contract is finalised. Clients who want to take the conversation off-platform before a contract is signed are a red flag. On top of that, you should also be able to negotiate boldly without putting yourself in the corner, all while studying your client for scammer patterns.

Have your own rules as a freelancer and follow them. Know Upwork's rules and follow them. Listen to the client's rules and expectations and see if you are prepared to follow them. This is the foundation of your Upwork survival journey.

The interview and contract negotiation phase is the most dangerous period of your freelance career. When you see people talking about how a single mistake cost them everything, this is the phase they're talking about. This is why the unofficial Upwork Reddit channel is a must-visit.

Protect yourself. Protect your account.

Last Word

How do you survive Upwork as a freelancer? This entire article can be distilled into one statement: Know and study the people on Upwork, and follow the rules.

Link to the You can also check the official Upwork subreddit, though it's much smaller than r/Upwork.

My name is Mxolisi Masuku. I write blogs like this and I have a newsletter called Systems For Humans where I talk about the software world beyond the technical considerations. For me, the software world works better when you think about who is on the other end as the guiding principle of whatever you are going to build. Subscribe and follow if you like this.

Build Your Stripe Checkout Like A Lawyer, Not Just A Developer

Mxolisi Masuku — Sat, 28 Mar 2026 10:58:13 +0000

Most developers and vibe coders build their Stripe checkout to accept payments. They don't build it to survive disputes with people, their customers. In Stripe's ecosystem, a single ban or badly handled chargeback can cost your business everything. This article is about how to make sure it doesn't.

Your Refund Policy Is Your First Line of Defence

Before you write a single line of checkout code, you need a refund and chargeback policy. Not a template you copied from the internet. A policy you have actually stress-tested against real scenarios.

For example, I am working on a platform that sells music beats. These fall under digital products. My thought process was: What happens when a customer pays for a beat, downloads it, then says they don't want it anymore and claims they never used it? What if they didn't download it? How would I even prove that? What if they come back after 2 days? 2 weeks? 2 months?

These disputes will come.

Some will be genuine, some will be fraudulent. Your policy is the wall between you keeping that money and Stripe taking it back.

This policy must be visible to the user. The user must accept it before they complete the purchase. The usual feature on most sites is a checkbox with: "I accept and agree to the terms and conditions." Simple. But if it's not there, you have nothing to stand on.

When building, you want to spend more of your initial time in the Stripe Sandbox where you test all of this before real money is involved. Play both God and customer. Simulate every scenario you can think of. Who has access to the payment gateway and at what stage? How are payments reflecting on your dashboard? Don't take the Sandbox for granted because it is the only environment where mistakes cost you nothing.

Capture Every Event. Prove Everything.

When a dispute hits, Stripe doesn't take your word for it. They want evidence. The card provider wants evidence. And if you haven't been recording the right events from the start, you have nothing to give them.

Every interaction between the user and your checkout process needs to be logged. Every click, every purchase, every policy agreement. What IP address did the user have? Was it consistent with their usual IP? Was the purchase made from a valid session? Did the user explicitly agree to the refund policy? Did you deliver the product? You need to be able to prove and demonstrate all of this with timestamps and unique IDs.

This is the part where you have to be deliberate with your AI. If you are vibe coding your checkout, there is a real chance your AI won't build evidence capture unless you specifically ask for it. AI is great at making the payment flow work. AI is not great at thinking about what happens when a customer disputes that payment six weeks later. You have to stress this requirement yourself.

Pro tip: Stripe has an AI Assistant for general queries and Agent Skills and Connectors for deeper integration. Use these if you are on Claude.

Event logging should be built as a feature not an afterthought. You want to be able to export all the evidence Stripe and card providers require, as a PDF or JSON, with all the required fields populated. When the dispute comes, and it will, you pull the file and submit it. That's the difference between keeping the money and losing it.

For reference, look at Stripe's dispute evidence object documentation. It tells you exactly what fields they expect: customer email, customer IP, product description, proof of delivery, refund policy disclosure, and more. Build your logging around that schema and you won't be scrambling when the first chargeback arrives.

Send Receipts and Invoices. Build Trust Before You Need It.

You can configure Stripe to send customer emails in Settings → Business → Email → Customer Emails. This isn't a legal requirement but think about it from the human side. You just made a $240 purchase and you don't get a receipt in your email. That's how distrust starts. That's how chargebacks start.

Receipts, invoices, upcoming deductions, subscription reminders. These are not nice-to-haves. They are evidence that you communicated with your customer. They are proof that the customer knew what they were paying for and when. If a dispute lands, a clean email trail showing receipts sent and subscription reminders delivered tells a very different story from silence.

If you want to go beyond Stripe's default emails and build custom branded ones, a tool like Resend works well for this. You create React template emails, hook them to your Stripe webhooks, and fire a custom receipt whenever a checkout.session.completed event lands. Resend gives you 100 emails a day for free. If you are hitting 100 emails a day, that means you got 100 customers a day and you can afford their $20 a month subscription.

Build For Humans. Defend Against The Worst Ones.

The thread running through this article is that you should build your software for human behaviour. Defend against malicious intent and protect yourself from legal punishment at the same time.

Most startups get burned not because their product was bad but because they didn't think about what happens when a real person with real emotions and real incentives interacts with their payment system. People forget what they bought. People regret purchases. People lie. And some people game the system because they know most small developers don't have their evidence in order.

Your checkout is not just a technical flow. It is a legal document, a communication channel and a defence mechanism. Treat it that way from day one.

Additional Reading

Stripe as the authority on why chargebacks happen and how to prevent them
If you are looking how rough things can get on chargebacks check this subReddit. The question: Are Stripe Chargebacks impossible to win.
Another Stripe Blog read: Can AI agents build real Stripe integrations? We built a benchmark to find out
If you ever decide that Stripe is not for you. Here is a video on alternatives.

My name is Mxolisi Masuku. I am a software engineer and a freelancer on Upwork. If you liked this, subscribe to my newsletter, Systems for Humans, where I write about the software world beyond the technical considerations.