Capacitor Native Settings

Capacitor plugin to open native settings screens for Android and iOS.

Plugin versions

| Capacitor version | Plugin version | | ---------- | ----------------------------------------- | | v7 | >= v7.0.1 | | v6 | >= v6.0.0 | | v5 | >= v5.0.0 | | v4 | >= v4.0.0 | | v3 | <= v2.0.1 |

Install

npm install capacitor-native-settings-extended
npx cap sync

Example

import { NativeSettings, AndroidSettings, IOSSettings } from 'capacitor-native-settings-extended';

/**
 * Note that the only supported option by Apple is "App".
 * Using other options might break in future iOS versions
 * or have your app rejected from the App Store.
 */
NativeSettings.open({
  optionAndroid: AndroidSettings.ApplicationDetails, 
  optionIOS: IOSSettings.App
})

NativeSettings.openAndroid({
  option: AndroidSettings.ApplicationDetails,
});

/**
 * Note that the only supported option by Apple is "App".
 * Using other options might break in future iOS versions
 * or have your app rejected from the App Store.
 */
NativeSettings.openIOS({
  option: IOSSettings.App,
});

API

• open(...)
• openAndroid(...)
• openIOS(...)
• getDebugState()
• Interfaces
• Enums

open(...)

open(option: PlatformOptions) => Promise<{ status: boolean; }>

Opens the specified options on android & ios. Note that the only supported option by Apple is "App". Using other options might break in future iOS versions or have your app rejected in the App Store.

| Param | Type | Description | | ------------ | ----------------------------------------------------------- | ---------------------------------------------- | | option | PlatformOptions | PlatformOptions |

Returns: Promise<{ status: boolean; }>

openAndroid(...)

openAndroid(option: AndroidOptions) => Promise<{ status: boolean; }>

Opens the specified option in android. Only use this if you have made sure the user is on android. This can be done by checking the platform before hand.

| Param | Type | Description | | ------------ | --------------------------------------------------------- | -------------------------------------------- | | option | AndroidOptions | AndroidOptions |

Returns: Promise<{ status: boolean; }>

openIOS(...)

openIOS(option: IOSOptions) => Promise<{ status: boolean; }>

Opens the specified option on iOS. Only use this if you have made sure the user is on iOS. This can be done by checking the platform before hand.

Note that the only supported option by Apple is "App". Using other options might break in future iOS versions or have your app rejected in the App Store.

| Param | Type | Description | | ------------ | ------------------------------------------------- | ------------------------------------ | | option | IOSOptions | IOSOptions |

Returns: Promise<{ status: boolean; }>

getDebugState()

getDebugState() => Promise<DeviceDebugState>

Reports whether the device currently has debug-oriented options enabled (Developer Options and/or ADB). Android only — on iOS and web every flag resolves to false.

This exists so apps can detect the states that make Stripe Terminal v5 refuse production Tap to Pay, and surface a clear instruction up front instead of letting discovery silently time out. Two distinct causes are reported: the device Developer Options / USB-Wi-Fi debugging being on (fails discovery with TAP_TO_PAY_INSECURE_ENVIRONMENT), and the app itself being a debuggable build (see {@link DeviceDebugState.appDebuggable}).

Returns: Promise<DeviceDebugState>

Interfaces

PlatformOptions

| Prop | Type | | ------------------- | ----------------------------------------------------------- | | optionAndroid | AndroidSettings | | optionIOS | IOSSettings |

AndroidOptions

| Prop | Type | | ------------ | ----------------------------------------------------------- | | option | AndroidSettings |

IOSOptions

| Prop | Type | | ------------ | --------------------------------------------------- | | option | IOSSettings |

DeviceDebugState

| Prop | Type | Description | | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | developerOptionsEnabled | boolean | True when Developer Options is enabled in the device settings (Settings.Global.DEVELOPMENT_SETTINGS_ENABLED on Android). | | adbEnabled | boolean | True when USB debugging / ADB is enabled (Settings.Global.ADB_ENABLED on Android). | | appDebuggable | boolean | True when the running app itself is a debuggable build (ApplicationInfo.FLAG_DEBUGGABLE on Android — i.e. android:debuggable="true" in the manifest, as produced by a debug build type). This is independent of the device Developer Options / ADB settings: Stripe Terminal v5 also refuses production Tap to Pay from a debuggable app ("Debuggable applications are not supported when using the production version of the Tap to Pay reader"), which no device toggle can clear — only installing a release build. | | anyDebugEnabled | boolean | Convenience OR of the individual flags — true when any debug option is on. |

Enums

AndroidSettings

| Members | Value | Description | | -------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accessibility | 'accessibility' | Show settings for accessibility modules | | Account | 'account' | Show add account screen for creating a new account | | AirplaneMode | 'airplane_mode' | Show settings to allow entering/exiting airplane mode | | Apn | 'apn' | Show settings to allow configuration of APNs | | ApplicationDetails | 'application_details' | Show screen of details about a particular application | | ApplicationDevelopment | 'application_development' | Show settings to allow configuration of application development-related settings | | Application | 'application' | Show settings to allow configuration of application-related settings | | AppNotification | 'app_notification' | Show settings to allow configuration of application-specific notifications | | BatteryOptimization | 'battery_optimization' | Show screen for controlling which apps can ignore battery optimizations | | Bluetooth | 'bluetooth' | Show settings to allow configuration of Bluetooth | | Captioning | 'captioning' | Show settings for video captioning | | Cast | 'cast' | Show settings to allow configuration of cast endpoints | | DataRoaming | 'data_roaming' | Show settings for selection of 2G/3G/4G | | Date | 'date' | Show settings to allow configuration of date and time | | Display | 'display' | Show settings to allow configuration of display | | Dream | 'dream' | Show Daydream settings | | Home | 'home' | Show Home selection settings | | Keyboard | 'keyboard' | Show settings to configure input methods, in particular allowing the user to enable input methods | | KeyboardSubType | 'keyboard_subtype' | Show settings to enable/disable input method subtypes | | Locale | 'locale' | Show settings to allow configuration of locale | | Location | 'location' | Show settings to allow configuration of current location sources | | ManageApplications | 'manage_applications' | Show settings to manage installed applications | | ManageAllApplications | 'manage_all_applications' | Show settings to manage all applications | | MemoryCard | 'memory_card' | Show settings for memory card storage | | Network | 'network' | Show settings for selecting the network operator | | NfcSharing | 'nfcsharing' | Show NFC Sharing settings | | NfcPayment | 'nfc_payment' | Show NFC Tap & Pay settings | | NfcSettings | 'nfc_settings' | Show NFC settings | | Print | 'print' | Show the top level print settings | | Privacy | 'privacy' | Show settings to allow configuration of privacy options | | QuickLaunch | 'quick_launch' | Show settings to allow configuration of quick launch shortcuts | | Search | 'search' | Show settings for global search | | Security | 'security' | Show settings to allow configuration of security and location privacy | | Settings | 'settings' | Show system settings | | ShowRegulatoryInfo | 'show_regulatory_info' | Show the regulatory information screen for the device | | Sound | 'sound' | Show settings to a llow configuration of sound and volume | | Storage | 'storage' | Show settings for internal storage | | Sync | 'sync' | Show settings to allow configuration of sync settings | | TextToSpeech | 'text_to_speech' | Show settings for configuring Text-to-Speech (TTS) output | | Usage | 'usage' | Show settings to control access to usage information | | UserDictionary | 'user_dictionary' | Show settings to manage the user input dictionary | | VoiceInput | 'voice_input' | Show settings to configure input methods, in particular allowing the user to enable input methods | | VPN | 'vpn' | Show settings to allow configuration of VPN | | Wifi | 'wifi' | Show settings to allow configuration of Wi-Fi | | WifiIp | 'wifi_ip' | Show settings to allow configuration of a static IP address for Wi-Fi | | Wireless | 'wireless' | Show settings to allow configuration of wireless controls such as Wi-Fi, Bluetooth and Mobile networks | | ConnectedDeviceDashboardActivity | 'connected_devices' | Show connected devices | | ZenMode | 'zen_mode' | Zen mode settings. | | ZenModePriority | 'zen_mode_priority' | Zen mode priority settings. Note that this may not work on every single device. See: https://github.com/RaphaelWoude/capacitor-native-settings/pull/63 | | ZenModeBlockedEffects | 'zen_mode_blocked_effects' | Zen mode blocked effects settings. Note that this may not work on every single device. See: https://github.com/RaphaelWoude/capacitor-native-settings/pull/63 |

IOSSettings

| Members | Value | Description | | ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | About | 'about' | Settings > About page | | App | 'app' | Opens your app-specific settings screen. Note that this is the only officially supported settings screen by Apple. | | AppNotification | 'appNotification' | Opens app-specific notification settings screen for iOS 15.4+; opens general app-specific settings for earlier versions." | | AutoLock | 'autoLock' | Used to set if and when the screen should be automatically locked. | | Bluetooth | 'bluetooth' | Bluetooth settings. Allows the users to enable/disable bluetooth and to search for devices. | | LocationCheckPermission | "locationCheckPermission" | Check Location permission. | | BluetoothCheckPermission | "bluetoothCheckPermission" | Check Bluetooth permission. | | BluetoothCheckPowerOn | "bluetoothCheckPowerOn" | Check whether Bluetooth is turned on. | | DateTime | 'dateTime' | Date and time settings. | | FaceTime | 'facetime' | FaceTime settings. | | General | 'general' | Opens iOS general settings screen. | | Keyboard | 'keyboard' | Keyboard settings. | | ICloud | 'iCloud' | iCloud settings. | | ICloudStorageBackup | 'iCloudStorageBackup' | iCloud Storage and Backup settings. | | International | 'international' | Language and region settings. | | LocationServices | 'locationServices' | Show settings to allow configuration of current location sources | | Music | 'music' | Music settings. | | Notes | 'notes' | Notes settings. | | Notifications | 'notifications' | Notifications settings. | | Phone | 'phone' | Phone settings. | | Photos | 'photos' | Photos settings. | | ManagedConfigurationList | 'managedConfigurationList' | Allows the user to manage configuration profiles that are installed on the phone. | | Reset | 'reset' | Screen where the user can reset the phone to factory settings. | | Ringtone | 'ringtone' | Ringtone settings. | | Sounds | 'sounds' | Used to set phone volume, vibration settings, etc. | | SoftwareUpdate | 'softwareUpdate' | Software update screen. | | Store | 'store' | Store settings. | | Tracking | 'tracking' | Tracking settings. | | VPN | 'vpn' | VPN settings. | | Wallpaper | 'wallpaper' | Wallpaper settings. | | WiFi | 'wifi' | WiFi settings. | | Tethering | 'tethering' | Tethering settings (used to create a hotspot with mobile data). | | DoNotDisturb | 'doNotDisturb' | Do Not Disturb settings. | | TouchIdPasscode | 'touchIdPasscode' | Touch id passcode settings. | | GuidedAccess | "guidedAccess" | | | GuidedAccessAutoLockTime | "guidedAccessAutoLockTime" | | | ScreenTime | 'screenTime' | Screen Time settings. | | Accessibility | 'accessibility' | Accessibility settings. |