{"id":13606699,"url":"https://github.com/PatilShreyas/permission-flow-android","last_synced_at":"2025-04-12T08:31:54.934Z","repository":{"id":41158802,"uuid":"504894810","full_name":"PatilShreyas/permission-flow-android","owner":"PatilShreyas","description":"Know about real-time state of a Android app Permissions with Kotlin Flow APIs.","archived":false,"fork":false,"pushed_at":"2024-06-28T01:02:24.000Z","size":1166,"stargazers_count":571,"open_issues_count":6,"forks_count":23,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-05T04:10:31.845Z","etag":null,"topics":["android","android-app","android-library","compose","coroutines-android","hacktoberfest","jetpack-compose","kotlin","kotlin-android","permission","permission-android","stateflow","stateflow-android"],"latest_commit_sha":null,"homepage":"https://PatilShreyas.github.io/permission-flow-android/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PatilShreyas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":"PatilShreyas","otechie":null,"custom":["https://www.paypal.me/PatilShreyas99/","https://github.com/sponsors/PatilShreyas/"]}},"created_at":"2022-06-18T16:29:13.000Z","updated_at":"2024-11-01T17:33:54.000Z","dependencies_parsed_at":"2024-01-16T23:30:39.731Z","dependency_job_id":"3c599f2b-e689-4a6e-910e-34f8137b7506","html_url":"https://github.com/PatilShreyas/permission-flow-android","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PatilShreyas%2Fpermission-flow-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PatilShreyas%2Fpermission-flow-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PatilShreyas%2Fpermission-flow-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PatilShreyas%2Fpermission-flow-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PatilShreyas","download_url":"https://codeload.github.com/PatilShreyas/permission-flow-android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223506344,"owners_count":17156677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-app","android-library","compose","coroutines-android","hacktoberfest","jetpack-compose","kotlin","kotlin-android","permission","permission-android","stateflow","stateflow-android"],"created_at":"2024-08-01T19:01:11.602Z","updated_at":"2024-11-07T11:31:36.197Z","avatar_url":"https://github.com/PatilShreyas.png","language":"Kotlin","funding_links":["https://issuehunt.io/r/PatilShreyas","https://www.paypal.me/PatilShreyas99/","https://github.com/sponsors/PatilShreyas/"],"categories":["Kotlin"],"sub_categories":[],"readme":"# Permission Flow for Android\n\nKnow about real-time state of a Android app Permissions with Kotlin Flow APIs. _Made with ❤️ for\nAndroid Developers_.\n\n[![Build](https://github.com/PatilShreyas/permission-flow-android/actions/workflows/build.yml/badge.svg)](https://github.com/PatilShreyas/permission-flow-android/actions/workflows/build.yml)\n[![Release](https://github.com/PatilShreyas/permission-flow-android/actions/workflows/release.yml/badge.svg)](https://github.com/PatilShreyas/permission-flow-android/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/PatilShreyas/permission-flow-android/branch/main/graph/badge.svg?token=6TOHNLQDVW)](https://codecov.io/gh/PatilShreyas/permission-flow-android)\n[![Maven Central](https://img.shields.io/maven-central/v/dev.shreyaspatil.permission-flow/permission-flow-android?label=Maven%20Central\u0026logo=android\u0026style=flat-square)](https://search.maven.org/artifact/dev.shreyaspatil.permission-flow/permission-flow-android)\n[![GitHub](https://img.shields.io/github/license/PatilShreyas/permission-flow-android?label=License)](LICENSE)\n\n[![dokka](https://img.shields.io/badge/Dokka-Docs-blueviolet.svg?style=flat\u0026logo=kotlin)](https://patilshreyas.github.io/permission-flow-android/docs/)\n[![kover](https://img.shields.io/badge/Kover-Coverage-blueviolet.svg?style=flat\u0026logo=kotlin)](https://patilshreyas.github.io/permission-flow-android/coverageReport/)\n\n## 💡Introduction\n\nIn big projects, app is generally divided in several modules and in such cases, if any individual\nmodule is just a data module (_not having UI_) and need to know state of a permission, it's not\nthat easy. This library provides a way to know state of a permission throughout the app and\nfrom any layer of the application safely.\n\n_For example, you can listen for state of contacts permission in class where you'll instantly show\nlist of contacts when permission is granted._\n\nIt's a simple and easy to use library. Just Plug and Play.\n\n## 🚀 Implementation\n\nYou can check [/app](/app) directory which includes example application for demonstration.\n\n### 1. Gradle setup\n\nIn `build.gradle` of app module, include this dependency\n\n```gradle\ndependencies {\n    implementation \"dev.shreyaspatil.permission-flow:permission-flow-android:$version\"\n    \n    // For using in Jetpack Compose\n    implementation \"dev.shreyaspatil.permission-flow:permission-flow-compose:$version\"\n}\n```\n\n_You can find latest version and changelogs in the [releases](https://github.com/PatilShreyas/permission-flow-android/releases)_.\n\n### 2. Observing a Permission State\n\n#### 2.1 Observing Permission with `StateFlow`\nA permission state can be subscribed by retrieving `StateFlow\u003cPermissionState\u003e` or `StateFlow\u003cMultiplePermissionState\u003e` as follows:\n\n```kotlin\nval permissionFlow = PermissionFlow.getInstance()\n\n// Observe state of single permission\nsuspend fun observePermission() {\n    permissionFlow.getPermissionState(Manifest.permission.READ_CONTACTS).collect { state -\u003e\n        if (state.isGranted) {\n            // Permission granted, access contacts.\n        } else if (state.isRationaleRequired == true) {\n            // Permission denied, but can be requested again\n        } else {\n            // Permission denied, and can't be requested again\n        }\n    }\n}\n\n// Observe state of multiple permissions\nsuspend fun observeMultiplePermissions() {\n    permissionFlow.getMultiplePermissionState(\n        Manifest.permission.READ_CONTACTS,\n        Manifest.permission.READ_SMS\n    ).collect { state -\u003e\n        // All permission states\n        val allPermissions = state.permissions\n\n        // Check whether all permissions are granted\n        val allGranted = state.allGranted\n\n        // List of granted permissions\n        val grantedPermissions = state.grantedPermissions\n\n        // List of denied permissions\n        val deniedPermissions = state.deniedPermissions\n        \n        // List of permissions requiring rationale\n        val permissionsRequiringRationale = state.permissionsRequiringRationale\n    }\n}\n```\n\n#### 2.2 Observing permissions in Jetpack Compose\n\nState of a permission and state of multiple permissions can also be observed in Jetpack Compose application as follows:\n\n```kotlin\n@Composable\nfun ExampleSinglePermission() {\n    val state by rememberPermissionState(Manifest.permission.CAMERA)\n    if (state.isGranted) {\n        // Permission granted\n    } else if (state.isRationaleRequired == true) {\n        // Permission denied, but can be requested again\n    } else {\n        // Permission denied, and can't be requested again\n    }\n}\n\n@Composable\nfun ExampleMultiplePermission() {\n    val state by rememberMultiplePermissionState(\n        Manifest.permission.CAMERA,\n        Manifest.permission.ACCESS_FINE_LOCATION,\n        Manifest.permission.READ_CONTACTS\n    )\n\n    if (state.allGranted) {\n        // Render something\n    }\n\n    val grantedPermissions = state.grantedPermissions\n    // Do something with `grantedPermissions`\n\n    val deniedPermissions = state.deniedPermissions\n    // Do something with `deniedPermissions`\n    \n    val permissionsRequiringRationale = state.permissionsRequiringRationale\n    // Do something with `permissionsRequiringRationale`\n}\n```\n\n### 3. Requesting permission with PermissionFlow\n\nIt's necessary to use utilities provided by this library to request permissions so that whenever permission state\nchanges, this library takes care of notifying respective flows.\n\n#### 3.1 Request permission from Activity / Fragment\n\nUse [`registerForPermissionFlowRequestsResult()`](https://patilshreyas.github.io/permission-flow-android/docs/permission-flow/dev.shreyaspatil.permissionFlow.utils/register-for-permission-flow-requests-result.html) method to get `ActivityResultLauncher`\nand use `launch()` method to request for permission.\n\n```kotlin\nclass ContactsActivity : AppCompatActivity() {\n\n    private val permissionLauncher = registerForPermissionFlowRequestsResult()\n\n    private fun askContactsPermission() {\n        permissionLauncher.launch(Manifest.permission.READ_CONTACTS, ...)\n    }\n}\n```\n\n#### 3.2 Request permission in Jetpack Compose\n\nUse [`rememberPermissionFlowRequestLauncher()`](https://patilshreyas.github.io/permission-flow-android/docs/permission-flow-compose/dev.shreyaspatil.permissionflow.compose/remember-permission-flow-request-launcher.html) method to get `ManagedActivityResultLauncher`\nand use `launch()` method to request for permission.\n\n```kotlin\n@Composable\nfun Example() {\n    val permissionLauncher = rememberPermissionFlowRequestLauncher()\n\n    Button(onClick = { permissionLauncher.launch(android.Manifest.permission.CAMERA, ...) }) {\n        Text(\"Request Permissions\")\n    }\n}\n```\n\n### 4. Manually notifying permission state changes ⚠️\n\nIf you're not using `ActivityResultLauncher` APIs provided by this library then\nyou will ***not receive permission state change updates***. But there's a provision by which\nyou can help this library to know about permission state changes.\n\nUse [`PermissionFlow#notifyPermissionsChanged()`](https://patilshreyas.github.io/permission-flow-android/docs/permission-flow/dev.shreyaspatil.permissionFlow/-permission-flow/notify-permissions-changed.html) to notify the permission state changes\nfrom your manual implementations.\n\nFor example:\n\n```kotlin\nclass MyActivity: AppCompatActivity() {\n    private val permissionFlow = PermissionFlow.getInstance()\n\n    private val permissionLauncher = registerForActivityResult(RequestPermission()) { isGranted -\u003e\n        permissionFlow.notifyPermissionsChanged(android.Manifest.permission.READ_CONTACTS)\n    }\n}\n```\n\n### 5. Manually Start / Stop Listening ⚠️\n\nThis library starts processing things lazily whenever `getPermissionState()` or `getMultiplePermissionState()` is called\nfor the first time. But this can be controlled with these methods:\n\n```kotlin\nfun doSomething() {\n    // Stops listening to the state changes of permissions throughout the application.\n    // This means the state of permission retrieved with [getMultiplePermissionState] method will not \n    // be updated after stopping listening. \n    permissionFlow.stopListening()\n\n    // Starts listening the changes of state of permissions after stopping listening\n    permissionFlow.startListening()\n}\n```\n\n### 6. What about Initialization? \n\nThis library automatically gets initialized with the App Startup library.\nIf you want to provide own coroutine dispatcher\n\n#### 6.1 Initialize **PermissionFlow** as follows (For example, in `Application` class)\n\n```kotlin\nclass MyApplication: Application() {\n    override fun onCreate() {\n        super.onCreate()\n        val permissionDispatcher = Executors.newFixedThreadPool(3).asCoroutineDispatcher()\n        PermissionFlow.init(this, permissionDispatcher)\n    }\n}\n```\n\n#### 6.2 Disable PermissionFlowInitializer in AndroidManifest.xml\n\nDisable auto initialization of library with default configuration using this:\n\n```xml\n\u003cprovider\n    android:name=\"androidx.startup.InitializationProvider\"\n    android:authorities=\"${applicationId}.androidx-startup\"\n    android:exported=\"false\"\n    tools:node=\"merge\"\u003e\n\n    \u003cmeta-data\n        android:name=\"dev.shreyaspatil.permissionFlow.initializer.PermissionFlowInitializer\"\n        android:value=\"androidx.startup\"\n        tools:node=\"remove\" /\u003e\n\u003c/provider\u003e\n```\n\n\n## 📄 API Documentation\n\n[Visit the API documentation](https://patilshreyas.github.io/permission-flow-android/docs/) of this library to get more information in detail. This documentation is generated using [Dokka](https://github.com/Kotlin/dokka).\n\n## 📊 Test coverage report\n\n[Check the Test Coverage Report](https://patilshreyas.github.io/permission-flow-android/coverageReport/) of this library. This is generated using [Kover](https://github.com/Kotlin/kotlinx-kover).\n\n---\n\n## 🙋‍♂️ Contribute\n\nRead [contribution guidelines](CONTRIBUTING.md) for more information regarding contribution.\n\n## 💬 Discuss?\n\nHave any questions, doubts or want to present your opinions, views? You're always welcome. You can [start discussions](https://github.com/PatilShreyas/permission-flow-android/discussions).\n\n## 📝 License\n\n```\nCopyright 2022 Shreyas Patil\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\n\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPatilShreyas%2Fpermission-flow-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPatilShreyas%2Fpermission-flow-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPatilShreyas%2Fpermission-flow-android/lists"}