Permission Flow for Android
Know about real-time state of a Android app Permissions with Kotlin Flow APIs. Made with
💡
Introduction
In big projects, app is generally divided in several modules and in such cases, if any individual module is just a data module (not having UI) and need to know state of a permission, it's not that easy. This library provides a way to know state of a permission throughout the app and from any layer of the application safely.
For example, you can listen for state of contacts permission in class where you'll instantly show list of contacts when permission is granted.
It's a simple and easy to use library. Just Plug and Play.
🚀
Implementation
You can check /app directory which includes example application for demonstration.
1. Gradle setup
In build.gradle of app module, include this dependency
dependencies {
implementation "dev.shreyaspatil.permission-flow:permission-flow-android:$version"
// For using in Jetpack Compose
implementation "dev.shreyaspatil.permission-flow:permission-flow-compose:$version"
}
You can find latest version and changelogs in the releases.
2. Initialization
Before using any API of the library, it needs to be initialized before.
Initialize PermissionFlow as follows (For example, in Application class):
class MyApplication: Application() {
override fun onCreate() {
super.onCreate()
PermissionFlow.init(this)
}
}
3. Observing a Permission State
3.1 Observing Permission with StateFlow
A permission state can be subscribed by retrieving StateFlow or StateFlow as follows:
val permissionFlow = PermissionFlow.getInstance()
// Observe state of single permission
suspend fun observePermission() {
permissionFlow.getPermissionState(android.Manifest.permission.READ_CONTACTS).collect { state ->
if (state.isGranted) {
// Do something
}
}
}
// Observe state of multiple permissions
suspend fun observeMultiplePermissions() {
permissionFlow.getMultiplePermissionState(
android.Manifest.permission.READ_CONTACTS,
android.Manifest.permission.READ_SMS
).collect { state ->
// All permission states
val allPermissions = state.permissions
// Check whether all permissions are granted
val allGranted = state.allGranted
// List of granted permissions
val grantedPermissions = state.grantedPermissions
// List of denied permissions
val deniedPermissions = state.deniedPermissions
}
}
3.2 Observing permissions in Jetpack Compose
State of a permission and state of multiple permissions can also be observed in Jetpack Compose application as follows:
@Composable
fun ExampleSinglePermission() {
val state by rememberPermissionState(Manifest.permission.CAMERA)
if (state.isGranted) {
// Render something
} else {
// Render something else
}
}
@Composable
fun ExampleMultiplePermission() {
val state by rememberMultiplePermissionState(
Manifest.permission.CAMERA
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.READ_CONTACTS
)
if (state.allGranted) {
// Render something
}
val grantedPermissions = state.grantedPermissions
// Do something with `grantedPermissions`
val deniedPermissions = state.deniedPermissions
// Do something with `deniedPermissions`
}
4. Requesting permission with PermissionFlow
It's necessary to use utilities provided by this library to request permissions so that whenever permission state changes, this library takes care of notifying respective flows.
4.1 Request permission from Activity / Fragment
Use registerForPermissionFlowRequestsResult() method to get ActivityResultLauncher and use launch() method to request for permission.
class ContactsActivity : AppCompatActivity() {
private val permissionLauncher = registerForPermissionFlowRequestsResult()
private fun askContactsPermission() {
permissionLauncher.launch(Manifest.permission.READ_CONTACTS, ...)
}
}
4.2 Request permission in Jetpack Compose
Use rememberPermissionFlowRequestLauncher() method to get ManagedActivityResultLauncher and use launch() method to request for permission.
@Composable
fun Example() {
val permissionLauncher = rememberPermissionFlowRequestLauncher()
Button(onClick = { permissionLauncher.launch(android.Manifest.permission.CAMERA, ...) }) {
Text("Request Permissions")
}
}
5. Manually notifying permission state changes
⚠️
If you're not using ActivityResultLauncher APIs provided by this library then you will not receive permission state change updates. But there's a provision by which you can help this library to know about permission state changes.
Use PermissionFlow#notifyPermissionsChanged() to notify the permission state changes from your manual implementations.
For example:
class MyActivity: AppCompatActivity() {
private val permissionFlow = PermissionFlow.getInstance()
private val permissionLauncher = registerForActivityResult(RequestPermission()) { isGranted ->
permissionFlow.notifyPermissionsChanged(android.Manifest.permission.READ_CONTACTS)
}
}
6. Manually Start / Stop Listening
⚠️
This library starts processing things lazily whenever getPermissionState() or getMultiplePermissionState() is called for the first time. But this can be controlled with these methods:
fun doSomething() {
// Stops listening to the state changes of permissions throughout the application.
// This means the state of permission retrieved with [getMultiplePermissionState] method will not
// be updated after stopping listening.
permissionFlow.stopListening()
// Starts listening the changes of state of permissions after stopping listening
permissionFlow.startListening()
}
📄
API Documentation
Visit the API documentation of this library to get more information in detail. This documentation is generated using Dokka.
📊
Test coverage report
Check the Test Coverage Report of this library. This is generated using Kover.
🙋♂️
Contribute
Read contribution guidelines for more information regarding contribution.
💬
Discuss?
Have any questions, doubts or want to present your opinions, views? You're always welcome. You can start discussions.
📝
License
Copyright 2022 Shreyas Patil
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
![[Update]: Bump mockk from 1.12.7 to 1.13.1](https://avatars.githubusercontent.com/in/29110?v=4)
85 Nov 17, 2022
3 Jun 30, 2022
1 Oct 30, 2021
313 Jan 4, 2023
2 Jan 1, 2022
0 Jan 7, 2022
0 Apr 21, 2022
0 Oct 31, 2021
615 Dec 16, 2022
1 Dec 15, 2021
3 Oct 17, 2022
14 Jul 28, 2022
22k Dec 31, 2022
1 Oct 4, 2022
6 Oct 17, 2022
46 Nov 29, 2022
2.1k Dec 30, 2022
2 Sep 3, 2022
5 Mar 31, 2022