System Date Time Change #

A Flutter plugin that detects manual changes to device date/time settings and identifies timezone mismatches across all platforms.

Overview #

This plugin provides native platform APIs to monitor and detect system date/time changes without relying on external libraries. It's particularly useful for applications that need to:

Detect when users manually change their device's date or time
Identify discrepancies between device time and the configured timezone
Monitor timezone changes in real-time
Ensure data integrity in time-sensitive applications

Features #

✅ Real-time Event Streaming: Receive instant notifications when system date/time changes
✅ Manual Polling: Check date/time status on-demand
✅ Native-Only Implementation: Uses platform-specific APIs without external dependencies
✅ Cross-Platform Support: Works on Android, iOS, Windows, macOS, Linux, and Web
✅ Auto Time Detection: Identifies if automatic time synchronization is enabled (where available)
✅ Timezone Monitoring: Detects timezone changes and potential mismatches

Platform Support #

Platform	Event-Based	Polling	Auto Time Detection
Android	✅	✅	✅
iOS	✅	✅	⚠️ Limited
macOS	✅	✅	⚠️ Limited
Windows	✅	✅	⚠️ Limited
Linux	⚠️ Polling	✅	⚠️ Limited
Web	⚠️ Polling	✅	❌

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  system_date_time_change: ^0.0.1

Then run:

flutter pub get

Usage #

Basic Example #

import 'package:system_date_time_change/system_date_time_change.dart';

// Create instance
final plugin = SystemDateTimeChange();

// Check current status
final status = await plugin.checkDateTimeStatus();
print('Auto time enabled: ${status.isAutoTimeEnabled}');
print('Current time: ${status.currentTime}');
print('Expected time: ${status.expectedTime}');
print('Timezone: ${status.timezone}');
print('Time difference: ${status.timeDifference}'); // Duration object
print('Device uptime: ${status.deviceUptime}'); // Duration object

Listening to Real-Time Events #

import 'package:system_date_time_change/system_date_time_change.dart';

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final _plugin = SystemDateTimeChange();
  StreamSubscription<DateTimeChangeEvent>? _subscription;

  @override
  void initState() {
    super.initState();
    _startListening();
  }

  void _startListening() {
    _subscription = _plugin.onDateTimeChanged.listen((event) {
      if (event.isManualChange) {
        print('⚠️ User manually changed the time!');
        print('Current: ${event.currentTime}');
        print('Expected: ${event.expectedTime}');
      }
      
      if (event.hasTimezoneMismatch) {
        print('⚠️ Timezone mismatch detected!');
        print('Timezone: ${event.timezone}');
      }
    });
  }

  @override
  void dispose() {
    _subscription?.cancel();
    _plugin.stopListening();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Date Time Monitor')),
        body: Center(child: Text('Monitoring system time...')),
      ),
    );
  }
}

Manual Status Check #

// Check status when needed
ElevatedButton(
  onPressed: () async {
    final status = await SystemDateTimeChange().checkDateTimeStatus();
    
    if (status.hasManualChange) {
      showDialog(
        context: context,
        builder: (context) => AlertDialog(
          title: Text('Warning'),
          content: Text('System time has been manually modified'),
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(context),
              child: Text('OK'),
            ),
          ],
        ),
      );
    }
  },
  child: Text('Check Time Status'),
)

API Reference #

SystemDateTimeChange #

Main class to interact with the plugin.

Methods

`checkDateTimeStatus()`

Returns the current date/time status.

Future<DateTimeChangeStatus> checkDateTimeStatus()

Returns: DateTimeChangeStatus object containing:

isAutoTimeEnabled: Whether automatic time sync is enabled
isAutoTimeZoneEnabled: Whether automatic timezone is enabled
hasManualChange: If time was manually modified
hasTimezoneMismatch: If there's a timezone discrepancy
currentTime: Current device time
expectedTime: Expected time based on device boot time
timezone: Current timezone identifier
timeDifferenceMs: Time difference in milliseconds (also available as timeDifference Duration)
deviceUptimeMs: Device uptime since last boot in milliseconds (also available as deviceUptime Duration)

`onDateTimeChanged`

Stream of date/time change events.

Stream<DateTimeChangeEvent> get onDateTimeChanged

Returns: Stream of DateTimeChangeEvent containing:

isManualChange: Whether the change was manual
hasTimezoneMismatch: If timezone is inconsistent
currentTime: Current device time
expectedTime: Expected time based on device boot time
timezone: Timezone identifier
timeDifferenceMs: Time difference in milliseconds (also available as timeDifference Duration)
deviceUptimeMs: Device uptime since last boot in milliseconds (also available as deviceUptime Duration)

`startListening()`

Starts listening for date/time changes.

Future<void> startListening()

`stopListening()`

Stops listening for date/time changes.

Future<void> stopListening()

Platform-Specific Details #

Android #

Uses BroadcastReceiver for ACTION_TIME_CHANGED, ACTION_TIMEZONE_CHANGED, ACTION_DATE_CHANGED
Checks Settings.Global.AUTO_TIME and AUTO_TIME_ZONE
Real-time event notifications

iOS #

Uses NSSystemTimeZoneDidChangeNotification and UIApplicationSignificantTimeChangeNotification
Limited access to auto-time settings (iOS system restriction)
Real-time event notifications

macOS #

Uses NSSystemTimeZoneDidChangeNotification and NSSystemClockDidChange
Requires admin privileges to check network time settings
Real-time event notifications

Windows #

Uses WM_TIMECHANGE Windows message
Monitors through window procedure
Real-time event notifications

Linux #

Uses polling mechanism (checks every 60 seconds)
Reads /etc/localtime and /etc/timezone
Limited systemd/dbus access without special permissions

Web #

Uses JavaScript Date API (very limited)
Polling-based detection (checks every 5 seconds)
Cannot reliably detect manual changes or auto-time settings

Example Application #

A complete example app is included in the example directory. To run it:

cd example
flutter run

The example demonstrates:

Real-time event monitoring
Manual status checking
Visual display of time changes
Event history tracking

Use Cases #

Financial Applications #

Prevent fraud by detecting when users manipulate device time to exploit time-based features.

Time-Tracking Apps #

Ensure accurate time logging by detecting manual time modifications.

Exam & Testing Apps #

Prevent cheating by monitoring time changes during timed assessments.

Subscription Services #

Detect attempts to bypass time-based trial periods.

Security Applications #

Monitor unauthorized system time modifications as a security measure.

Limitations #

iOS/macOS: Cannot determine if auto-time is enabled due to system restrictions
Linux: Requires polling; no native event-based API without elevated permissions
Web: Very limited detection capabilities; relies on polling and heuristics
Network Time: Plugin doesn't directly access network time servers (uses system APIs only)

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

Author #

Alasri
Developer specializing in native plugin development and system-level programming.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog #

See CHANGELOG.md for a list of changes.

Support #

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Note: This plugin uses native system APIs and respects platform security restrictions. Some features may be limited on certain platforms due to OS-level permissions and privacy policies.

system_date_time_change 1.0.1 system_date_time_change: ^1.0.1 copied to clipboard

Metadata