XXPermissions Documentation

repository·master·Indexed 27 days ago

https://github.com/getactivity/xxpermissions

A permission request framework for Android applications designed to handle permission management and requests. It provides a builder pattern for requesting multiple permissions in Java and Kotlin, supports Android 10+ Scoped Storage configuration, and includes a static API for checking permissions and navigating to system settings.

Tokens: 6.4K
Snippets: 6
Records: 8
Agent score: 42%

What's inside XXPermissions

Access English documentation for xxpermissions
master
The primary English documentation for the xxpermissions framework is located in README-en.md. Use this file for installation guides, API references, and usage instructions in English.
https://github.com/getactivity/xxpermissions/blob/master/README.md

Install XXPermissions

master

To integrate XXPermissions, you must first add the JitPack repository to your Gradle configuration, then add the dependencies to your app module.

// For Gradle < 7.0, add to build.gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// For Gradle >= 7.0, add to settings.gradle
dependencyResolutionManagement {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// In your app module's build.gradle
android {
    compileOptions {
        targetCompatibility JavaVersion.VERSION_1_8
        sourceCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    implementation 'com.github.getActivity:DeviceCompat:2.6'
    implementation 'com.github.getActivity:XXPermissions:28.3'
}

Configure Scoped Storage in AndroidManifest
master
If your project has adapted to Android 10 scoped storage, you must inform XXPermissions by adding a meta-data tag to your AndroidManifest.xml. This allows the framework to correctly determine whether to use READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE or MANAGE_EXTERNAL_STORAGE for permission requests.
```
<manifest>
    <application>
        
        <meta-data
            android:name="ScopedStorage"
            android:value="true" />
    </application>
</manifest>
```
https://github.com/getactivity/xxpermissions/blob/master/README-en.md
Configure Scoped Storage for Android 10+
master
If your project has already adapted to Android 10 Scoped Storage, notify XXPermissions by adding a meta-data tag to your AndroidManifest.xml. If you have NOT adapted to Scoped Storage, you should use MANAGE_EXTERNAL_STORAGE to read external storage files instead of READ_EXTERNAL_STORAGE or WRITE_EXTERNAL_STORAGE.
```
<manifest>
    <application>
        
        <meta-data
            android:name="ScopedStorage"
            android:value="true" />
    </application>
</manifest>
```
https://github.com/getactivity/xxpermissions/blob/master/README.md
Request permissions in Java
master
Use the XXPermissions.with(activity) builder pattern to request one or multiple permissions. The request method provides a callback with grantedList and deniedList.
https://github.com/getactivity/xxpermissions/blob/master/README.md

Request permissions in Kotlin

master

Use the XXPermissions.with(activity) builder pattern to request one or multiple permissions. The request method provides a callback with grantedList and deniedList.

XXPermissions.with(this)
    // Request multiple permissions
    .permission(PermissionLists.getRecordAudioPermission())
    .permission(PermissionLists.getCameraPermission())
    // .unchecked() // Optional: disable error detection locally
    .request { grantedList, deniedList ->
        val allGranted = deniedList.isEmpty()
        if (!allGranted) {
            // Check if user selected 'Do Not Ask Again'
            val doNotAskAgain = XXPermissions.isDoNotAskAgainPermissions(activity, deniedList)
            // Handle failure logic
            return@request
        }
        // Handle success logic
    }

Reference: XXPermissions Static API

master

A collection of static methods for checking permissions, managing permission lists, and navigating to system settings.

// Check if one or multiple permissions are granted
XXPermissions.isGrantedPermission(@NonNull Context context, @NonNull IPermission permission);
XXPermissions.isGrantedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.isGrantedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Get granted permissions from a list
XXPermissions.getGrantedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.getGrantedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Get denied permissions from a list
XXPermissions.getDeniedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.getDeniedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Compare permissions
XXPermissions.equalsPermission(@NonNull IPermission permission, @NonNull IPermission permission2);
XXPermissions.equalsPermission(@NonNull IPermission permission, @NonNull String permissionName);
XXPermissions.equalsPermission(@NonNull String permissionName1, @NonNull String permissionName2);

// Check if list contains a permission
XXPermissions.containsPermission(@NonNull List<IPermission> permissions, @NonNull IPermission permission);
XXPermissions.containsPermission(@NonNull List<IPermission> permissions, @NonNull String permissionName);

// Check if permission is a health permission
XXPermissions.isHealthPermission(@NonNull IPermission permission);

// Check if user selected 'Do Not Ask Again' (Must be called within the request callback)
XXPermissions.isDoNotAskAgainPermission(@NonNull Activity activity, @NonNull IPermission permission);
XXPermissions.isDoNotAskAgainPermissions(@NonNull Activity activity, @NonNull IPermission[] permissions);
XXPermissions.isDoNotAskAgainPermissions(@NonNull Activity activity, @NonNull List<IPermission> permissions);

// Navigate to Permission Settings (Context version)
XXPermissions.startPermissionActivity(@NonNull Context context);
XXPermissions.startPermissionActivity(@NonNull Context context, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Context context, @NonNull List<IPermission> permissions);

// Navigate to Permission Settings (Activity version)
XXPermissions.startPermissionActivity(@NonNull Activity activity);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Navigate to Permission Settings (Fragment version)
XXPermissions.startPermissionActivity(@NonNull Fragment fragment);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Navigate to Permission Settings (AndroidX Fragment version)
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Global Settings
XXPermissions.setPermissionDescriptionClass(@Nullable Class<? extends OnPermissionDescription> clazz);
XXPermissions.setPermissionInterceptorClass(@Nullable Class<? extends OnPermissionInterceptor> clazz);
XXPermissions.setCheckMode(boolean checkMode);

Reference: XXPermissions API methods

master

The following methods are available for checking permissions, managing settings, and navigating to permission pages.

// Check if a single permission is granted
XXPermissions.isGrantedPermission(@NonNull Context context, @NonNull IPermission permission);
XXPermissions.isGrantedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.isGrantedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Get the granted permissions from a permission list
XXPermissions.getGrantedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.getGrantedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Get the denied permissions from a permission list
XXPermissions.getDeniedPermissions(@NonNull Context context, @NonNull IPermission[] permissions);
XXPermissions.getDeniedPermissions(@NonNull Context context, @NonNull List<IPermission> permissions);

// Determine whether the two permissions are equal
XXPermissions.equalsPermission(@NonNull IPermission permission, @NonNull IPermission permission2);
XXPermissions.equalsPermission(@NonNull IPermission permission, @NonNull String permissionName);
XXPermissions.equalsPermission(@NonNull String permissionName1, @NonNull String permissionName2);

// Determine whether a certain permission is included in the permission list
XXPermissions.containsPermission(@NonNull List<IPermission> permissions, @NonNull IPermission permission);
XXPermissions.containsPermission(@NonNull List<IPermission> permissions, @NonNull String permissionName);

// Check if a permission is a health permission
XXPermissions.isHealthPermission(@NonNull IPermission permission);

// Check if a permission has been denied with the "Never ask again" option selected 
XXPermissions.isDoNotAskAgainPermission(@NonNull Activity activity, @NonNull IPermission permission);
XXPermissions.isDoNotAskAgainPermissions(@NonNull Activity activity, @NonNull IPermission[] permissions);
XXPermissions.isDoNotAskAgainPermissions(@NonNull Activity activity, @NonNull List<IPermission> permissions);

// Navigate to the permission settings page (Context version)
XXPermissions.startPermissionActivity(@NonNull Context context);
XXPermissions.startPermissionActivity(@NonNull Context context, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Context context, @NonNull List<IPermission> permissions);

// Navigate to the permission settings page (Activity version)
XXPermissions.startPermissionActivity(@NonNull Activity activity);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull Activity activity, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Navigate to the permission settings page (Android Fragment version)
XXPermissions.startPermissionActivity(@NonNull Fragment fragment);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull Fragment fragment, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Navigate to the permission settings page (AndroidX Fragment version)
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull IPermission... permissions);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions, @IntRange(from = 1, to = 65535) int requestCode);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull IPermission permission, @Nullable OnPermissionCallback callback);
XXPermissions.startPermissionActivity(@NonNull androidx.fragment.app.Fragment xFragment, @NonNull List<IPermission> permissions, @Nullable OnPermissionCallback callback);

// Set the permission description provider (Global setting)
XXPermissions.setPermissionDescriptionClass(@Nullable Class<? extends OnPermissionDescription> clazz);

// Set the permission request interceptor (Global setting)
XXPermissions.setPermissionInterceptorClass(@Nullable Class<? extends OnPermissionInterceptor> clazz);

// Set whether to enable error detection mode (Global setting)
XXPermissions.setCheckMode(boolean checkMode);