SoulPermission Documentation

To use SoulPermission in your Android project, add the dependency to your build.gradle file. It is highly recommended to use AndroidX.

For AndroidX projects (Recommended):

dependencies {
  implementation 'com.github.soulqw:SoulPermission:1.4.0'
}

For legacy projects (Support Library 28): If your application has not yet migrated to AndroidX, use version 1.2.2. Note that version 1.2.2 is the last version to support support28 and will not receive new features.

dependencies {
   implementation 'com.qw:soulpermission:1.2.2'
}

To avoid infinite loops and ensure correct behavior:

• Where to call: Call permission requests in onCreate().
• Where NOT to call: Do not call permission requests in onResume(). If a permission is not yet granted, calling it in onResume() can cause the app to enter a loop of requesting and returning to the activity.

SoulPermission uses a ContentProvider for automatic initialization. However, if your project uses frameworks that replace the Application class (e.g., Tinker, Tencent LeGu), automatic initialization might fail. In such cases, manually call SoulPermission.init(this) in your Application.onCreate() method.

public class SimpleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Manually initialize if auto-init fails due to Application replacement
        SoulPermission.init(this);
    }
}

You can request a group of permissions simultaneously using checkAndRequestPermissions combined with Permissions.build().

If you do not need callbacks, use SimplePermissionsAdapter.

SoulPermission.getInstance().checkAndRequestPermissions(
                Permissions.build(Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE),
                new CheckRequestPermissionsListener() {
                    @Override
                    public void onAllPermissionOk(Permission[] allPermissions) {
                        // All requested permissions are granted
                    }

                    @Override
                    public void onPermissionDenied(Permission[] refusedPermissions) {
                        // At least one permission was refused
                    }
                });

SoulPermission provides global configuration methods:

• SoulPermission.skipOldRom(true): Skips the old permission system on certain ROMs (defaults permissions to granted).
• SoulPermission.setDebug(true): Enables debug mode to print logs and show Toast messages for troubleshooting.
• SoulPermission.init(Application): Manual initialization.

To check if a permission is currently granted without triggering a request dialog, use checkSinglePermission (for one) or checkPermissions (for multiple).

// Check a single permission
Permission checkResult = SoulPermission.getInstance().checkSinglePermission(Manifest.permission.ACCESS_FINE_LOCATION);

// Check multiple permissions
// (Use checkPermissions() for a series of permissions)

If a user has permanently denied a permission, you can use goApplicationSettings to direct them to the app's system settings page.

SoulPermission.getInstance().goApplicationSettings(new GoAppDetailCallBack() {
    @Override
    public void onBackFromAppDetail(Intent data) {
        // Logic to execute when user returns from settings
    }
});

SoulPermission supports checking and requesting special system permissions such as NOTIFICATION, SystemAlert (floating windows), UNKNOWN_APP_SOURCES (install unknown apps), and WRITE_SYS_SETTINGS.

Check a special permission:

boolean checkResult = SoulPermission.getInstance().checkSpecialPermission(Special.NOTIFICATION);

Check and request a special permission:

SoulPermission.getInstance().checkAndRequestPermission(Special.UNKNOWN_APP_SOURCES, new SpecialPermissionListener() {
    @Override
    public void onGranted(Special permission) {
        // Permission granted
    }

    @Override
    public void onDenied(Special permission) {
        // Permission denied
    }
});