Skip to content

TXAVLOG/txa-settings-permission

BranchesTags

Repository files navigation

txa-settings-permission

npm license platform capacitor

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

Made with ❤️ by TXA · github.com/TXAVLOG

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

2 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages