capacitor-app-settings

v7.2.0

Published

10 days ago

Capacitor plugin to open native app settings on iOS and Android

0High
0Medium
0Low

barodrig

capacitor plugin native

📱 Capacitor App Settings

Capacitor plugin to open native app settings on iOS and Android

Languages: 🇺🇸 English | 🇫🇷 Français

✨ Features

🍎 iOS: Opens app settings using the official UIApplication.openSettingsURLString API
🤖 Android: Support for 43 system settings (notifications, WiFi, Bluetooth, location, etc.)
🔐 Permission management: Check, request, and handle 17 native permissions across iOS and Android
🔒 Store-compliant: Uses only official APIs, validated for App Store & Google Play
📦 TypeScript: Full type definitions for better developer experience
🎯 Simple: Unified API to handle both iOS and Android

📦 Installation

npm install capacitor-app-settings
npx cap sync

🚀 Usage

Basic - Open app settings

import { AppSettings } from "capacitor-app-settings";

// Opens the app settings
// iOS: App-specific settings
// Android: Application details
await AppSettings.openSettings();

Advanced - Android-specific settings

import { AppSettings, AndroidSetting } from "capacitor-app-settings";

// Open notification settings (Android)
await AppSettings.openSettings({
    android: AndroidSetting.AppNotification,
});

// Open WiFi settings (Android)
await AppSettings.openSettings({
    android: AndroidSetting.Wifi,
});

// Open location settings (Android)
await AppSettings.openSettings({
    android: AndroidSetting.Location,
});

📋 API

`openSettings(options?: OpenSettingsOptions)`

Opens the native system settings for the app.

Parameters:

interface OpenSettingsOptions {
    android?: AndroidSetting; // Android-specific setting (ignored on iOS)
}

Returns: Promise<{ success: boolean }>

🔐 Permissions API

`checkPermission(options: CheckPermissionOptions)`

Check the status of a single permission.

import { AppSettings, PermissionType } from "capacitor-app-settings";

const result = await AppSettings.checkPermission({
    permission: PermissionType.Camera,
});
console.log(result.status); // "granted" | "denied" | "prompt" | "prompt-with-rationale" | "not-applicable"

`checkAllPermissions()`

Check all 17 permissions at once.

const all = await AppSettings.checkAllPermissions();
for (const [perm, status] of Object.entries(all.permissions)) {
    console.log(`${perm}: ${status}`);
}

`checkSpecificPermissions(options: CheckSpecificPermissionsOptions)`

Check a subset of permissions.

const result = await AppSettings.checkSpecificPermissions({
    permissions: [PermissionType.Camera, PermissionType.Microphone],
});

`requestPermission(options: RequestPermissionOptions)`

Request a permission. If denied, automatically opens app settings.

const result = await AppSettings.requestPermission({
    permission: PermissionType.Notifications,
});
if (result.openedSettings) {
    console.log("User was redirected to Settings");
}

Returns: Promise<RequestPermissionResult>

interface RequestPermissionResult {
    status: AppSettingsPermissionState;
    openedSettings: boolean; // true if Settings was opened (permission was denied)
}

Permission Statuses

| Status | Meaning | | ----------------------- | ------------------------------------------------------------ | | granted | Permission granted | | denied | Permission denied (permanently on iOS, or denied on Android) | | prompt | Never requested, system dialog can be shown | | prompt-with-rationale | Android: denied once but dialog still possible | | not-applicable | Does not exist on this platform or API level |

Supported Permissions (17)

| Permission | iOS | Android | API min | | ------------------------- | ------------------- | --------------------------------------------------------- | ------- | | Camera | AVFoundation | CAMERA | - | | Microphone | AVFoundation | RECORD_AUDIO | - | | LocationWhenInUse | CoreLocation | ACCESS_FINE_LOCATION + ACCESS_COARSE_LOCATION | - | | BackgroundLocation | CoreLocation | ACCESS_BACKGROUND_LOCATION | 29 | | Notifications | UserNotifications | POST_NOTIFICATIONS | 33 | | PhotoLibrary | Photos | READ_MEDIA_IMAGES (33+) / READ_EXTERNAL_STORAGE (<33) | - | | Contacts | Contacts | READ_CONTACTS | - | | Calendar | EventKit | READ_CALENDAR | - | | ActivityRecognition | CoreMotion | ACTIVITY_RECOGNITION | 29 | | Biometrics | LocalAuthentication | USE_BIOMETRIC | 28 | | Reminders | EventKit | not-applicable | - | | AppTrackingTransparency | ATT (iOS 14+) | not-applicable | - | | SpeechRecognition | Speech | not-applicable | - | | BatteryOptimization | not-applicable | PowerManager | 23 | | BodySensors | not-applicable | BODY_SENSORS | 20 | | ExactAlarm | not-applicable | SCHEDULE_EXACT_ALARM | 31 | | Bluetooth | CoreBluetooth | BLUETOOTH_CONNECT | 31 |

Permission Usage Examples

import { AppSettings, PermissionType } from "capacitor-app-settings";

// Check a permission
const { status } = await AppSettings.checkPermission({
    permission: PermissionType.Camera,
});

// Request a permission (opens Settings if denied)
const request = await AppSettings.requestPermission({
    permission: PermissionType.Notifications,
});
if (request.openedSettings) {
    console.log("User was redirected to Settings");
}

// Check all permissions
const all = await AppSettings.checkAllPermissions();
for (const [perm, status] of Object.entries(all.permissions)) {
    console.log(`${perm}: ${status}`);
}

🤖 Supported Android Settings

The plugin supports 43 types of settings on Android via the AndroidSetting enum:

| Category | Settings | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | App | ApplicationDetails, AppNotification, Application, ApplicationDevelopment | | Network | Wifi, WifiIp, Bluetooth, Wireless, Apn, DataRoaming, Network | | Location | Location | | System | Settings, Display, Sound, Storage, Battery, Date, Locale | | Security | Security, Privacy, BatteryOptimization | | Accessibility | Accessibility, Captioning | | Accounts | Account, Sync | | Development | ApplicationDevelopment | | Other | Cast, Dream, Home, Keyboard, KeyboardSubtype, MemoryCard, NfcSettings, NfcPayment, NfcSharing, Print, QuickLaunch, Search, ShowRegulatoryInfo, Usage, UserDictionary, VoiceInput, Vpn, ZenMode, ZenModePriority, ZenModeBlockedEffects |

Complete AndroidSetting List

enum AndroidSetting {
    // Application settings
    ApplicationDetails = "application_details",
    AppNotification = "app_notification",
    Application = "application",
    ApplicationDevelopment = "application_development",

    // Network and connectivity
    Wifi = "wifi",
    WifiIp = "wifi_ip",
    Bluetooth = "bluetooth",
    Wireless = "wireless",
    Apn = "apn",
    DataRoaming = "data_roaming",
    Network = "network",

    // Location
    Location = "location",

    // System
    Settings = "settings",
    Display = "display",
    Sound = "sound",
    Storage = "storage",
    Date = "date",
    Locale = "locale",

    // Security and privacy
    Security = "security",
    Privacy = "privacy",
    BatteryOptimization = "battery_optimization",

    // Accessibility
    Accessibility = "accessibility",
    Captioning = "captioning",

    // Accounts
    Account = "account",
    Sync = "sync",

    // Other
    Cast = "cast",
    Dream = "dream",
    Home = "home",
    Keyboard = "keyboard",
    KeyboardSubtype = "keyboard_subtype",
    ManageApplications = "manage_applications",
    ManageAllApplications = "manage_all_applications",
    MemoryCard = "memory_card",
    NfcSettings = "nfc_settings",
    NfcPayment = "nfc_payment",
    NfcSharing = "nfcsharing",
    Print = "print",
    QuickLaunch = "quick_launch",
    Search = "search",
    ShowRegulatoryInfo = "show_regulatory_info",
    TextToSpeech = "text_to_speech",
    Usage = "usage",
    UserDictionary = "user_dictionary",
    VoiceInput = "voice_input",
    Vpn = "vpn",
    ZenMode = "zen_mode",
    ZenModePriority = "zen_mode_priority",
    ZenModeBlockedEffects = "zen_mode_blocked_effects",
}

🍎 iOS Behavior

On iOS, the plugin exclusively uses UIApplication.openSettingsURLString, which always opens your app's specific settings page (notifications, permissions, etc.).

The AndroidSetting options are ignored on iOS.

Note: On iOS Simulator, behavior may be unstable. Always test on a physical device for reliable results.

💡 Use Cases

Example 1: Request notification permission

import { AppSettings, PermissionType } from "capacitor-app-settings";

async function requestNotifications() {
    const { status } = await AppSettings.checkPermission({
        permission: PermissionType.Notifications,
    });

    if (status !== "granted") {
        const result = await AppSettings.requestPermission({
            permission: PermissionType.Notifications,
        });

        if (result.openedSettings) {
            console.log("User was redirected to Settings");
        }
    }
}

Example 2: Toggle with permission handling

import { AppSettings, PermissionType } from "capacitor-app-settings";

const handleNotificationToggle = async () => {
    const { status } = await AppSettings.checkPermission({
        permission: PermissionType.Notifications,
    });

    if (status === "granted") {
        // Permission granted -> Open settings to manage
        await AppSettings.openSettings();
    } else {
        // Permission not granted -> Request it
        await AppSettings.requestPermission({
            permission: PermissionType.Notifications,
        });
    }
};

Example 3: Request location permission

import { AppSettings, PermissionType } from "capacitor-app-settings";

async function requestLocation() {
    const { status } = await AppSettings.checkPermission({
        permission: PermissionType.LocationWhenInUse,
    });

    if (status !== "granted") {
        const result = await AppSettings.requestPermission({
            permission: PermissionType.LocationWhenInUse,
        });

        if (result.openedSettings) {
            console.log("User was redirected to Settings");
        }
    }
}

⚙️ Configuration

iOS Info.plist

Add the required usage description keys for each permission you use:

| Permission | Info.plist Key | | ----------------------- | -------------------------------------------------------------------------------------- | | Camera | NSCameraUsageDescription | | Microphone | NSMicrophoneUsageDescription | | LocationWhenInUse | NSLocationWhenInUseUsageDescription | | BackgroundLocation | NSLocationAlwaysAndWhenInUseUsageDescription + NSLocationWhenInUseUsageDescription | | Contacts | NSContactsUsageDescription | | Calendar | NSCalendarsUsageDescription | | ActivityRecognition | NSMotionUsageDescription | | Biometrics | NSFaceIDUsageDescription (Face ID only) | | Reminders | NSRemindersUsageDescription | | AppTrackingTransparency | NSUserTrackingUsageDescription | | SpeechRecognition | NSSpeechRecognitionUsageDescription | | Bluetooth | NSBluetoothAlwaysUsageDescription | | PhotoLibrary | NSPhotoLibraryUsageDescription | | Notifications | None (requested at runtime) |

Android AndroidManifest.xml

Add the required permissions to your AndroidManifest.xml:

| Permission | Manifest permission(s) | API min | | ------------------- | ---------------------------------------------------------- | ------- | | Camera | android.permission.CAMERA | - | | Microphone | android.permission.RECORD_AUDIO | - | | LocationWhenInUse | ACCESS_FINE_LOCATION + ACCESS_COARSE_LOCATION | - | | BackgroundLocation | ACCESS_BACKGROUND_LOCATION | 29 | | Notifications | POST_NOTIFICATIONS | 33 | | PhotoLibrary | READ_MEDIA_IMAGES (33+) or READ_EXTERNAL_STORAGE (<33) | - | | Contacts | READ_CONTACTS | - | | Calendar | READ_CALENDAR | - | | ActivityRecognition | ACTIVITY_RECOGNITION | 29 | | Bluetooth | BLUETOOTH_CONNECT | 31 | | BodySensors | BODY_SENSORS | 20 | | BatteryOptimization | REQUEST_IGNORE_BATTERY_OPTIMIZATIONS | 23 | | ExactAlarm | SCHEDULE_EXACT_ALARM | 31 | | Biometrics | USE_BIOMETRIC | 28 |

🔧 Compatibility

Capacitor: 7.0.0+
iOS: 13.0+
Android: API 22+ (Android 5.1+)

Note: AppTrackingTransparency requires iOS 14+.

🏗️ Architecture

iOS

The plugin uses the official iOS API:

UIApplication.openSettingsURLString to open app settings
Compatible with latest iOS versions
App Store compliant

Android

The plugin maps options to Android Intent actions:

Settings.ACTION_APPLICATION_DETAILS_SETTINGS (app settings)
Settings.ACTION_APP_NOTIFICATION_SETTINGS (notifications)
And 41 other Android system actions

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for more information.

Local Development

# Clone the repo
git clone https://github.com/allohouston/capacitor-app-settings.git
cd capacitor-app-settings

# Install dependencies
npm install

# Build the plugin
npm run build

# Verify the plugin
npm run verify

🐛 Bugs & Support

If you encounter any issues, please open an issue with:

Plugin version
Capacitor version
Platform (iOS/Android)
Issue description
Reproduction code (if possible)

📝 Changelog

See CHANGELOG.md for version history.

Built with ❤️ for Capacitor by ALLOHOUSTON