txa-settings-permission

Capacitor plugin by TXA — Mở tất cả các màn hình cài đặt cấp quyền Android, tự động tương thích theo Android version, log đẹp khi lỗi.

📦 NPM · 🐛 Issues · 👤 TXA

✨ Tính năng

| Tính năng | Mô tả | |-----------|-------| | 📂 All Files Access | MANAGE_EXTERNAL_STORAGE (Android 11+) | | 🪟 Overlay | Hiển thị trên ứng dụng khác (Android 6+) | | 📦 Install Unknown Apps | Cài từ nguồn không rõ (Android 8+) | | 🔋 Battery Optimization | Bỏ qua tối ưu hóa pin (Android 6+) | | 🔔 Notification Settings | Cài đặt thông báo & DND | | ♿ Accessibility | Quyền trợ năng | | 📊 Usage Stats | Quyền dữ liệu sử dụng (Android 5.1+) | | 📡 System Settings | WiFi, Location, Bluetooth, NFC, Sound, Display... | | 🔍 Runtime Check | Check bất kỳ permission nào theo tên | | 📋 Bulk Check | Check nhiều permission cùng lúc | | 📱 APK Installation | Cài đặt APK từ đường dẫn file | | 🔄 Auto-compat | Tự fallback theo Android version | | 📝 Đẹp Log | Mọi kết quả đều kèm log object chi tiết |

📋 Yêu cầu

• Capacitor >= 4.0.0
• Android SDK >= 22 (Android 5.0+)
• Node.js >= 16

⚠️ Plugin này chỉ hoạt động trên Android. Trên Web/iOS trả về mock (granted: true).

🚀 Cài đặt

npm install txa-settings-permission
npx cap sync

Sau khi cài, script postinstall tự kiểm tra @capacitor/core. Nếu thiếu sẽ báo:

❌ THIẾU DEPENDENCY BẮT BUỘC: @capacitor/core
   npm install @capacitor/core @capacitor/android @capacitor/cli

⚙️ Cấu hình Android

Thêm permissions vào AndroidManifest.xml

Chỉ thêm permission app bạn thực sự cần:

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest ...>

    <!-- All Files Access (Android 11+) -->
    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

    <!-- Overlay -->
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

    <!-- Bỏ qua tối ưu hóa pin -->
    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />

    <!-- Storage (Android < 13) -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="29" />

    <!-- Media (Android 13+) -->
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

    <!-- Notifications (Android 13+) -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

</manifest>

Register plugin thủ công (nếu cần)

Capacitor 6+ tự auto-discovery. Nếu cần register thủ công trong MainActivity.java:

import online.txa.settingspermission.TxaSettingsPermissionPlugin;

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        registerPlugin(TxaSettingsPermissionPlugin.class);
        super.onCreate(savedInstanceState);
    }
}

📖 API Reference

getDeviceInfo()

Lấy thông tin thiết bị và feature flags theo Android version.

const info = await TxaSettingsPermission.getDeviceInfo();
// {
//   androidSdk: 34, androidRelease: "14",
//   manufacturer: "samsung", model: "SM-S918B",
//   supportsManageAllFiles: true,     // Android 11+
//   supportsOverlay: true,            // Android 6+
//   supportsInstallUnknownApps: true, // Android 8+
//   supportsBatteryOptimization: true,
//   supportsMediaPermissions: true,   // Android 13+
//   ...
// }

checkAllRequired()

Check toàn bộ permission phổ biến cùng lúc. Nên gọi khi app khởi động.

const { checks, androidSdk } = await TxaSettingsPermission.checkAllRequired();

// checks.manageAllFiles   → MANAGE_EXTERNAL_STORAGE
// checks.overlay          → Draw Overlay
// checks.installUnknownApps
// checks.batteryOptimization
// checks.camera, microphone, location
// checks.readMediaVideo (Android 13+)
// checks.postNotifications (Android 13+)
// checks.readExternalStorage (Android < 13)

All Files Access (Android 11+)

// Check
const { granted, log } = await TxaSettingsPermission.checkManageAllFiles();
console.log(log.message); // "Đã có quyền MANAGE_EXTERNAL_STORAGE"

// Mở Settings
const result = await TxaSettingsPermission.openManageAllFiles();
// result.opened = true  → Settings đã mở
// result.granted = true → Đã có quyền từ trước
// result.log.level = 'warn' nếu fallback sang màn hình chung

Android < 11: Tự động { granted: true }, không mở gì.

Overlay (Android 6+)

const { granted } = await TxaSettingsPermission.checkOverlay();
if (!granted) await TxaSettingsPermission.openOverlaySettings();

Install Unknown Apps (Android 8+)

const { granted } = await TxaSettingsPermission.checkInstallUnknownApps();
if (!granted) {
    await TxaSettingsPermission.openInstallUnknownApps();
    // Android 8+: màn hình riêng cho app
    // Android 5-7: mở Security Settings (log.level = 'warn')
}

Battery Optimization (Android 6+)

const { ignoring } = await TxaSettingsPermission.checkBatteryOptimization();
if (!ignoring) {
    const result = await TxaSettingsPermission.openBatteryOptimization();
    // Tự fallback sang Battery Saver Settings nếu device không hỗ trợ
    console.log(result.log.level, result.log.message);
}

Notifications

await TxaSettingsPermission.openNotificationSettings();     // Cài đặt thông báo
await TxaSettingsPermission.openNotificationPolicyAccess(); // DND / Không làm phiền

APK Installation

Cài đặt APK từ đường dẫn file trên thiết bị.

const result = await TxaSettingsPermission.installApk({
    path: '/storage/emulated/0/Download/app.apk'
});

// result.success = true  → Đã mở trình cài đặt
// result.log.message = "Đã mở trình cài đặt APK"

Lưu ý:

• Android 7+: Sử dụng FileProvider để chia sẻ file
• Android < 7: Sử dụng Uri trực tiếp
• Cần quyền MANAGE_EXTERNAL_STORAGE cho file ở external storage
• Cần quyền REQUEST_INSTALL_PACKAGES trong AndroidManifest.xml

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

System Settings

await TxaSettingsPermission.openWifiSettings();
await TxaSettingsPermission.openLocationSettings();
await TxaSettingsPermission.openBluetoothSettings();
await TxaSettingsPermission.openNfcSettings();
await TxaSettingsPermission.openDateTimeSettings();
await TxaSettingsPermission.openLanguageSettings();
await TxaSettingsPermission.openStorageSettings();
await TxaSettingsPermission.openDisplaySettings();
await TxaSettingsPermission.openSoundSettings();
await TxaSettingsPermission.openAccessibilitySettings();
await TxaSettingsPermission.openUsageStatsSettings();
await TxaSettingsPermission.openDeviceAdminSettings();
await TxaSettingsPermission.openSettings(); // App Settings tổng quát

Runtime Permission Check

// Check 1 permission
const { granted, log } = await TxaSettingsPermission.checkRuntimePermission({
    permission: 'android.permission.CAMERA',
});

// Check nhiều permission cùng lúc
const result = await TxaSettingsPermission.checkMultiplePermissions({
    permissions: [
        'android.permission.CAMERA',
        'android.permission.RECORD_AUDIO',
        'android.permission.READ_MEDIA_VIDEO',
    ],
});
console.log('Tất cả đã cấp:', result.allGranted);
console.log('Thiếu:', result.missing);

📝 Log Object

Mọi method đều trả về log kèm theo:

{
    level: 'info',              // 'info' | 'warn' | 'error'
    message: 'Đã mở...',       // Mô tả bằng tiếng Việt
    action: 'MANAGE_ALL_FILES', // Tên action
    success: true,
    androidVersion: 34,         // Android SDK
    androidRelease: '14',       // Version string
    timestamp: 1700000000000    // Unix ms
}

| Level | Ý nghĩa | |-------|---------| | info | Thành công hoặc không cần thiết (Android version cũ) | | warn | Fallback sang phương án dự phòng | | error | Không thể thực hiện |

🔄 Ví dụ đầy đủ — Setup Permission khi khởi động

import { TxaSettingsPermission } from 'txa-settings-permission';
import { App } from '@capacitor/app';
import { Capacitor } from '@capacitor/core';

export async function setupPermissions() {
    if (!Capacitor.isNativePlatform()) return;

    const info = await TxaSettingsPermission.getDeviceInfo();
    console.log(`Android ${info.androidRelease} (SDK ${info.androidSdk})`);

    const { checks } = await TxaSettingsPermission.checkAllRequired();

    if (!checks.manageAllFiles && info.supportsManageAllFiles) {
        await TxaSettingsPermission.openManageAllFiles();
        await waitForResume();
    }

    if (!checks.overlay && info.supportsOverlay) {
        await TxaSettingsPermission.openOverlaySettings();
        await waitForResume();
    }

    if (!checks.batteryOptimization && info.supportsBatteryOptimization) {
        await TxaSettingsPermission.openBatteryOptimization();
        await waitForResume();
    }
}

function waitForResume(): Promise<void> {
    return new Promise(resolve => {
        const h = App.addListener('appStateChange', async ({ isActive }) => {
            if (isActive) { (await h).remove(); resolve(); }
        });
    });
}

📖 API Reference Detail

Dưới đây là danh sách đầy đủ các Method có trong Package và mức độ tương thích.

🛡️ Cấp quyền hệ thống (System & Special Permissions)

| Method | Check Status | Open Settings | Android | Ghi chú | |:---|:---:|:---:|:---:|:---| | Manage All Files | checkManageAllFiles() | openManageAllFiles() | 11+ | Quyền quản lý toàn bộ tệp | | Overlay | checkOverlay() | openOverlaySettings() | 6.0+ | Hiển thị trên ứng dụng khác | | Install Unknown Apps | checkInstallUnknownApps() | openInstallUnknownApps() | 8.0+ | Cài đặt ứng dụng từ nguồn lạ | | Battery Optimization | checkBatteryOptimization() | openBatteryOptimization() | 6.0+ | Bỏ qua tối ưu hóa pin | | Notifications | - | openNotificationSettings() | 5.0+ | Cài đặt thông báo của App | | Do Not Disturb | - | openNotificationPolicyAccess() | 6.0+ | Truy cập chính sách không làm phiền | | Accessibility | - | openAccessibilitySettings() | 5.0+ | Cài đặt Trợ năng | | Usage Stats | - | openUsageStatsSettings() | 5.1+ | Dữ liệu sử dụng ứng dụng | | Device Admin | - | openDeviceAdminSettings() | 5.0+ | Quản trị thiết bị | | APK Installation | - | installApk({ path: string }) | 5.0+ | Cài đặt APK từ file path |

⚙️ Cài đặt hệ thống (General System Settings)

Mở trực tiếp các màn hình cài đặt của thiết bị:

| Method | Chức năng | Android | |:---|:---|:---:| | openWifiSettings() | Cài đặt WiFi | 5.0+ | | openLocationSettings() | Cài đặt Vị trí | 5.0+ | | openBluetoothSettings() | Cài đặt Bluetooth | 5.0+ | | openNfcSettings() | Cài đặt NFC | 5.0+ | | openDateTimeSettings() | Cài đặt Ngày & Giờ | 5.0+ | | openLanguageSettings() | Cài đặt Ngôn ngữ | 5.0+ | | openStorageSettings() | Cài đặt Bộ nhớ | 5.0+ | | openDisplaySettings() | Cài đặt Hiển thị | 5.0+ | | openSoundSettings() | Cài đặt Âm thanh | 5.0+ | | openAppDetailsSettings()| Thông tin ứng dụng (App Info) | 5.0+ | | openSettings() | Cài đặt ứng dụng (App Settings) | 5.0+ |

🔍 Kiểm tra quyền (Runtime Checks)

| Method | Tham số | Kết quả | |:---|:---|:---| | getDeviceInfo() | Không | Trả về Model, SDK, và các cờ supports... | | checkRuntimePermission() | { permission: string } | Check 1 quyền cụ thể (vd: CAMERA) | | checkMultiplePermissions()| { permissions: string[] }| Check mảng nhiều quyền cùng lúc | | checkAllRequired() | Không | Check nhanh tất cả các quyền phổ biến |

📋 Compatibility Matrix Summary

📋 API Summary & Compatibility

Dưới đây là bảng tổng hợp các phương thức chính và mức độ tương thích trên các phiên bản Android.

| Method | Ý nghĩa | Tham số | Android tương thích | Ghi chú | |:---|:---|:---|:---:|:---| | getDeviceInfo | Lấy thông tin thiết bị | Không | 5.0+ | Trả về SDK, Model, Manufacturer và Support flags | | checkManageAllFiles | Check quyền quản lý tệp | Không | 11+ | SDK < 30 tự trả về granted: true | | openManageAllFiles | Mở màn hình cấp quyền tệp | Không | 11+ | SDK < 30 trả về log warn và không mở màn hình | | checkOverlay | Check quyền Overlay | Không | 6.0+ | | | openOverlaySettings | Mở màn hình vẽ trên app khác | Không | 6.0+ | | | checkBatteryOptimization | Check tối ưu hóa pin | Không | 6.0+ | | | openBatteryOptimization | Mở màn hình tối ưu pin | Không | 6.0+ | Mặc định mở danh sách tất cả ứng dụng | | openAppNotificationSettings | Mở thông báo của App | Không | 5.0+ | Tự động chọn app hiện tại (SDK 26+) | | openAccessibilitySettings | Mở cài đặt Trợ năng | Không | 5.0+ | Mở màn hình danh sách dịch vụ trợ năng | | openAppDetailsSettings | Mở thông tin ứng dụng | Không | 5.0+ | Màn hình sytem app info (Clear data, Force stop...) | | openSettings | Mở cài đặt App chung | Không | 5.0+ | Màn hình cài đặt tổng quát của ứng dụng | | installApk | Cài đặt APK từ file | { path: string } | 5.0+ | Mở trình cài đặt APK từ đường dẫn file | | checkMultiplePermissions | Check nhiều quyền cùng lúc | { permissions: string[] } | 5.0+ | Truyền vào mảng android.permission.NAME |

📄 License

MIT © TXA