@chancn/capacitor-date-and-time-settings

A Capacitor plugin (Android only) to check whether automatic date & time and timezone settings are enabled on a device, and to open the device's Date & Time settings page.

📦 Installation

npm install @chancn/capacitor-date-and-time-settings
npx cap sync

🔌 Register the Plugin

import { registerPlugin } from '@capacitor/core';

export interface AutoTimePlugin {
  isAutoDateTimeEnabled(): Promise<{ enabled: boolean }>;
  isAutoTimeZoneEnabled(): Promise<{ enabled: boolean }>;
  getCurrentTimeZone(): Promise<{ timeZone: string }>;
  isTimeZoneCorrect(options: { expectedZoneId: string }): Promise<{ 
    isCorrect: boolean; 
    currentZone: string; 
  }>;
  openDateTimeSettings(): Promise<void>;
}

export const AutoTime = registerPlugin<AutoTimePlugin>('AutoTime');

⚡ Usage in React/Ionic (Android Only)

import React, { useEffect, useState } from 'react';
import { IonButton, IonContent, IonPage } from '@ionic/react';
import { AutoTime } from '@chancn/capacitor-date-and-time-settings';
import { toaster } from 'your-toaster-lib'; // Replace with your toaster implementation

const EXPECTED_TIMEZONE = 'Asia/Manila';

const DateTimeScreen: React.FC = () => {
  const [isTimeSettingsValid, setIsTimeSettingsValid] = useState(true);
  const [timeSettingsMessage, setTimeSettingsMessage] = useState('');
  const [isCheckingSettings, setIsCheckingSettings] = useState(false);

  const openDeviceSettings = async () => {
    try {
      await AutoTime.openDateTimeSettings();
      toaster.success('Opening Date & Time settings...');

      setTimeout(async () => {
        await recheckTimeSettings();
      }, 2000);
    } catch (error) {
      console.error('Error opening settings:', error);
      toaster.warning('Please manually open Settings > Date & Time');
    }
  };

  const recheckTimeSettings = async () => {
    setIsCheckingSettings(true);
    try {
      const autoDate = await AutoTime.isAutoDateTimeEnabled();
      const autoZone = await AutoTime.isAutoTimeZoneEnabled();
      const timezone = await AutoTime.getCurrentTimeZone();

      const missingSettings: string[] = [];
      if (!autoDate.enabled) missingSettings.push('Automatic Date & Time');
      if (!autoZone.enabled) missingSettings.push('Automatic Time Zone');
      if (EXPECTED_TIMEZONE && timezone.timeZone !== EXPECTED_TIMEZONE) {
        missingSettings.push(`Correct Timezone (should be ${EXPECTED_TIMEZONE})`);
      }

      if (missingSettings.length > 0) {
        setIsTimeSettingsValid(false);
        setTimeSettingsMessage(`Please enable: ${missingSettings.join(', ')}`);
        toaster.warning('Settings still need to be configured');
      } else {
        setIsTimeSettingsValid(true);
        setTimeSettingsMessage('');
        toaster.success('Time settings verified! You can now punch in/out.');
      }
    } catch (error) {
      console.error('Error rechecking time settings:', error);
      toaster.danger('Unable to verify settings. Please try again.');
    } finally {
      setIsCheckingSettings(false);
    }
  };

  useEffect(() => {
    const checkTimeSettings = async () => {
      setIsCheckingSettings(true);
      try {
        const autoDate = await AutoTime.isAutoDateTimeEnabled();
        const autoZone = await AutoTime.isAutoTimeZoneEnabled();
        const timezone = await AutoTime.getCurrentTimeZone();

        const missingSettings: string[] = [];
        if (!autoDate.enabled) missingSettings.push('Automatic Date & Time');
        if (!autoZone.enabled) missingSettings.push('Automatic Time Zone');
        if (EXPECTED_TIMEZONE && timezone.timeZone !== EXPECTED_TIMEZONE) {
          missingSettings.push(`Correct Timezone (should be ${EXPECTED_TIMEZONE})`);
        }

        if (missingSettings.length > 0) {
          setIsTimeSettingsValid(false);
          setTimeSettingsMessage(`Please enable: ${missingSettings.join(', ')}`);
        } else {
          setIsTimeSettingsValid(true);
          setTimeSettingsMessage('');
        }
      } catch (error) {
        console.error('Error checking time settings:', error);
        setIsTimeSettingsValid(false);
        setTimeSettingsMessage('Unable to verify time settings');
      } finally {
        setIsCheckingSettings(false);
      }
    };

    checkTimeSettings();

    const handleAppResume = () => {
      recheckTimeSettings();
    };

    document.addEventListener('resume', handleAppResume);
    window.addEventListener('focus', handleAppResume);

    return () => {
      document.removeEventListener('resume', handleAppResume);
      window.removeEventListener('focus', handleAppResume);
    };
  }, []);

  return (
    <IonPage>
      <IonContent className="ion-padding">
        <IonButton onClick={openDeviceSettings} disabled={isCheckingSettings}>
          Open Date & Time Settings
        </IonButton>

        <div style={{ marginTop: 20 }}>
          {isCheckingSettings ? 'Checking...' : timeSettingsMessage}
        </div>

        {isTimeSettingsValid && <div>✅ Time settings are correct!</div>}
      </IonContent>
    </IonPage>
  );
};

export default DateTimeScreen;

✅ Plugin Methods (Android Only)

| Method | Description | |--------|------------| | isAutoDateTimeEnabled() | Checks if Automatic Date & Time is enabled. | | isAutoTimeZoneEnabled() | Checks if Automatic Time Zone is enabled. | | getCurrentTimeZone() | Returns the device's current timezone. | | isTimeZoneCorrect({ expectedZoneId }) | Checks if the current timezone matches the expected one. | | openDateTimeSettings() | Opens the device's Date & Time settings page. |

⚠️ Notes

• Works only on Android devices. iOS is not supported yet.
• Always run npx cap sync after installing or updating the plugin.
• Can be integrated with modals, alerts, or toasters to guide users to enable correct settings.

License

MIT