moko-permissions

On Android, the PermissionsController must be bound to the Activity lifecycle to ensure permission requests are handled correctly and safely. Call permissionsController.bind(activity) within your Activity's onCreate method.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
        
    val viewModel = getViewModel {
        // Pass the platform implementation of the permission controller to a common code.
        ViewModel(PermissionsController())
    }
    
    // Binds the permissions controller to the activity lifecycle.
    viewModel.permissionsController.bind(activity)
}

For Compose Multiplatform, you can use PermissionsControllerFactory to create a controller.

If you are using standard Compose, use BindEffect(controller) to bind the controller to the LocalLifecycleOwner.

If you are using moko-mvvm, ensure you bind the controller in your Composable to handle configuration changes on Android correctly.

@Composable
fun Sample() {
    val factory: PermissionsControllerFactory = rememberPermissionsControllerFactory()
    val controller: PermissionsController = remember(factory) { factory.createPermissionsController() }
    val coroutineScope: CoroutineScope = rememberCoroutineScope()
    
    Button(
        onClick = {
            coroutineScope.launch {
                controller.providePermission(Permission.REMOTE_NOTIFICATION)
            }
        }
    ) {
        Text(text = "give permissions")
    }
}

The openAppSettings() method triggers the iOS system to open the settings application directly to the settings page for your app. This is useful when a user has denied a permission and you need to guide them to manually enable it in the system settings.

val controller = PermissionsController()
controller.openAppSettings()

On iOS, the PermissionsController implements the PermissionsControllerProtocol to manage runtime permissions. It provides methods to request permissions, check their current state, and open the system settings app.

Note that this implementation relies on the delegate property of the Permission object to perform the actual platform-specific logic.

val controller = PermissionsController()

// Request a permission
controller.providePermission(permission)

// Check if a permission is granted
val isGranted = controller.isPermissionGranted(permission)

// Get the full permission state
val state = controller.getPermissionState(permission)

// Open system settings
controller.openAppSettings()

When a user denies a permission request, the library throws a DeniedException. You can catch this exception to identify which specific Permission was denied and react accordingly (e.g., by showing a rationale UI).

DeniedException is the base class for all permission denial errors in the library.

try {
    permissionsController.requestPermission(Permission.CAMERA)
} catch (e: DeniedException) {
    val deniedPermission = e.permission
    // Handle the denial of the specific permission
}

If a user has selected 'Don't ask again' (or the platform equivalent) and the permission is permanently denied, the library throws a DeniedAlwaysException. This is a subclass of DeniedException.

Catching this specific exception allows you to distinguish between a simple denial (where you might ask again) and a permanent denial (where you must direct the user to the system settings).

try {
    permissionsController.requestPermission(Permission.CAMERA)
} catch (e: DeniedAlwaysException) {
    // The user has permanently denied this permission.
    // You should likely direct them to the app settings.
} catch (e: DeniedException) {
    // The user just denied it this time.
}

When a user cancels a permission request (e.g., by dismissing the system dialog), the library throws a RequestCanceledException. This exception contains a permission property that identifies which specific permission was being requested at the time of cancellation. You should catch this exception to prevent your application from crashing and to handle the user's decision to deny the request gracefully.

try {
    permissionsController.requestPermission(Permission.CAMERA)
} catch (e: RequestCanceledException) {
    // The user canceled the request for the specific permission
    println("Permission ${e.permission} was canceled by the user")
}