app_badger 3.3.0

A Flutter plugin to manage app badge counts on Android, iOS, and macOS with modern Swift Package Manager and federated architecture support.

app_badger

A Flutter plugin for app icon badge counts on Android, iOS, and macOS.

This repository was built as an independent badge plugin for app-level badge management. The API is kept distinct from common badge plugin names to reduce naming collisions while still supporting the standard launcher and platform behaviors expected by mobile apps.

What this package does

• Updates numeric app badges on supported Android launchers
• Supports iOS badge updates through the native notification system
• Supports macOS Dock badge updates via the native Dock tile API
• Exposes a small, consistent Dart API for set, clear, query and permission flows
• Includes lifecycle helpers and a native event stream for app-level badge syncing

Key API

import 'package:app_badger/app_badger.dart';

// Set badge
await AppBadgeController.setBadgeValue(7);

// Clear badge and notification tray (iOS/Android)
await AppBadgeController.clearAllNotifications();

// Check battery optimization (Android)
final isOptimized = await AppBadgeController.isIgnoringBatteryOptimizations();

// Check device badge capabilities
final capability = await AppBadgeController.getCapability();
print('Badge supported: ${capability.supported} via ${capability.method}');

// Android-specific launcher info
if (Platform.isAndroid) {
  final info = await AppBadgeController.getAndroidBadgeInfo();
  print('Launcher: ${info?.launcher}');
}

Legacy names remain available as deprecated wrappers for compatibility:

await AppBadger.updateBadgeCount(7);
await AppBadger.removeBadge();

Installation

Add the package to your app:

dependencies:
  app_badger: ^3.3.0

Then run:

flutter pub get

Platform setup

Android

Add notification permission for Android 13+:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

For reliable badging on OEM devices (Samsung, Huawei, etc.), this plugin automatically handles the necessary provider permissions in the background.

iOS

Add the usage description to ios/Runner/Info.plist:

<key>NSUserNotificationUsageDescription</key>
<string>Notifications are required to display app badges</string>

macOS

No special entitlement is required for Dock badges.

Recommended startup flow

import 'package:app_badger/app_badger.dart';

Future<void> initializeBadges() async {
  final granted = await AppBadgeController.requestBadgePermission();
  if (granted) {
    await AppBadgeController.restoreBadgeState();
  }
}

Best-effort resilience fixes

This plugin now restores the last persisted badge count on app resume instead of blindly clearing it. This reduces badge loss when the OS or launcher clears the count while the app is backgrounded.

For apps that want a different UX, set:

class _MyPageState extends State<MyPage> with BadgeLifecycleObserver {
  @override
  void initState() {
    super.initState();
    restoreBadgeOnResume = true;
    clearBadgeOnResume = false;
    initBadgeLifecycle();
  }
}

Platform limitations

• Android: some launchers display only a notification dot instead of a numeric badge.
• Android 13+: POST_NOTIFICATIONS is required for badge notification fallback.
• iOS: app badge updates usually require notification permission and may require APNs for terminated-state updates.
• macOS: Dock badge behavior depends on the Dock API and app lifecycle state.
• Badge support is best-effort and depends on the OS, launcher, and app state; no platform can be forced to show a badge when it refuses to do so.

Event stream

AppBadgeController.events.listen((event) {
  print('Badge event: $event');
});

Android notification configuration

AppBadgeController.setAndroidNotificationConfig(
  channelId: 'app_badger_channel',
  channelName: 'Badge updates',
  smallIcon: 'ic_stat_notify_badge',
);

Platform Support

Feature	Android	iOS	macOS
Numeric Badges	✅	✅	✅
Clear Badge	✅	✅	✅
Clear All Notifications	✅	✅ (1)	✅
Permission Request	✅ (13+)	✅	✅
Capability Detection	✅	✅	✅
Launcher Detection	✅	✅	✅
Battery Opt Check	✅	✅	✅

(1) On iOS, clearAllNotifications() clears both the badge and the notification center tray.

Key Limitations

• Background Terminated State: Local badge updates cannot run if the app is killed by the OS. Use server-side push payloads (FCM/APNs) for terminated-state badge updates.
• iOS Notification Tray: Standard clearBadgeValue() only resets the icon number. Use clearAllNotifications() to clear both the badge and the tray.
• Android Launcher Fragmentation: Some launchers (like the stock Pixel Launcher) do not support numeric badges and will display a "Notification Dot" instead.

Android Compatibility

Support for Android depends on the launcher. This plugin uses a fallback chain:

1. ShortcutBadger: Supports many OEM launchers (Samsung, Sony, Xiaomi, etc.)
2. Notification Sync: If enabled, uses a low-priority notification to trigger badge dots on launchers like Pixel.

Manufacturer Support Matrix

Manufacturer / Launcher	Numeric Badge	Notification Dot	Method
Samsung (One UI)	✅	✅	Manufacturer API
Xiaomi (MIUI/HyperOS)	✅	✅	ShortcutBadger
Huawei (EMUI)	✅	✅	Manufacturer API
Sony (Xperia)	✅	✅	ShortcutBadger
OPPO / Vivo / Realme	✅	✅	ShortcutBadger
Google Pixel Launcher	❌	✅	Notification Sync
OnePlus (OxygenOS)	✅	✅	ShortcutBadger
Motorola	❌	✅	Notification Sync
Nova Launcher	✅	✅	ShortcutBadger

Monorepo management

This repository uses Melos for the workspace setup and validation workflow.

melos run get
melos run analyze
melos run test
melos run format
melos run clean

Third-party and legal notice

This project is an independent Flutter badge package. It is not presented as a fork of, or as a direct copy of, the upstream flutter_app_badger project.

This package includes Android launcher badge support through ShortcutBadger, which remains under its own Apache 2.0 license. The project continues to keep dependency notices with the source.

License

MIT