Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/debug45/PermissionWizard

🔮 An ultimate library for iOS and macOS system permissions management. The easiest way to check or request a permission.
https://github.com/debug45/PermissionWizard

apple camera catalyst ios ipad iphone location mac macos notifications permissions photos plist swift

Last synced: 8 days ago
JSON representation

🔮 An ultimate library for iOS and macOS system permissions management. The easiest way to check or request a permission.

Awesome Lists containing this project

README 

        
# 🔮 PermissionWizard



[![CocoaPods](https://img.shields.io/badge/CocoaPods-supported-success)](https://cocoapods.org/pods/PermissionWizard)

![Carthage](https://img.shields.io/badge/Carthage-supported-success)



[Читать на русском](https://github.com/debug45/PermissionWizard/blob/master/README.ru.md)



It is an ultimate tool for system permissions management. No longer you have to understand system API of each new permission type or search it on the Stack Overflow. 😄



## Advantages



📱 Supports the newest features of **iOS 17** and **macOS 14 Sonoma**




🖥 Works great with **Mac Catalyst**



✋ Supports **all existing permission types**




🛡 Provides crash free by **validating your plist** keys




📬 Use **async/await** and **completion blocks** even where it is not provided by default system API




🛣 Forget about **thread management** by specifying desired dispatch queues to invoke completion blocks (optional)



🚀 Completely written in **Swift**




🍭 Unifies your code **regardless of permission types** you are working with




🖼 Includes **native icons** and **localized strings** for your UI (optional)




🍕 Modular, add to your project **only what you need**




🪁 Does not contain anything redundant



## Supported Types



                 



## Requirements



- iOS 14 / macOS 11 Big Sur

- Xcode 15

- Swift 5.5



## Installation



### [CocoaPods](https://cocoapods.org)



To integrate **PermissionWizard** into your Xcode project, add it to your `Podfile`:



```ruby

pod 'PermissionWizard'

```



By default, the library will be installed fully.



Due to Apple’s policy regarding system permissions, your app may be rejected due to mention of API that is not actually used. It is recommended to install only components that you need. In this case **you will not have any troubles**. ⚠️



```ruby

pod 'PermissionWizard/Assets' # Icons and localized strings

pod 'PermissionWizard/Bluetooth'

pod 'PermissionWizard/Calendars'

pod 'PermissionWizard/Camera'

pod 'PermissionWizard/Contacts'

pod 'PermissionWizard/FaceID'

pod 'PermissionWizard/Health'

pod 'PermissionWizard/Home'

pod 'PermissionWizard/LocalNetwork'

pod 'PermissionWizard/Location'

pod 'PermissionWizard/Microphone'

pod 'PermissionWizard/Motion'

pod 'PermissionWizard/Music'

pod 'PermissionWizard/Notifications'

pod 'PermissionWizard/Photos'

pod 'PermissionWizard/Reminders'

pod 'PermissionWizard/Siri'

pod 'PermissionWizard/SpeechRecognition'

pod 'PermissionWizard/Tracking'

```



Do not specify `pod 'PermissionWizard'` if you install separate components.



### [Carthage](https://github.com/Carthage/Carthage)



To integrate **PermissionWizard** into your Xcode project, add it to your `Cartfile`:



```ogdl

github "debug45/PermissionWizard"

```



By default, the library is compiled fully when you build the project.



Due to Apple’s policy regarding system permissions, your app may be rejected due to mention of API that is not actually used. It is recommended to enable only components that you need. In this case **you will not have any troubles**. ⚠️



To enable only components that you need, create the `PermissionWizard.xcconfig` file in the root directory of your project. Put appropriate settings into the file according to the following template:



```

ENABLED_FEATURES = ASSETS BLUETOOTH CALENDARS CAMERA CONTACTS FACE_ID HEALTH HOME LOCAL_NETWORK LOCATION MICROPHONE MOTION MUSIC NOTIFICATIONS PHOTOS REMINDERS SIRI SPEECH_RECOGNITION TRACKING

SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) $(ENABLED_FEATURES) CUSTOM_SETTINGS

```



Customize the first line of the template removing unnecessary component names.



## How to Use



Using of **PermissionWizard** is incredibly easy!



```swift

import PermissionWizard



if useSwiftConcurrency {

    await Permission.contacts.checkStatus() // .notDetermined

} else {

    Permission.contacts.checkStatus { status in

        status // .notDetermined

    }

}



do {

    if useSwiftConcurrency {

        try await Permission.location.requestAccess(whenInUseOnly: true) // (value: .whenInUseOnly, isAccuracyReducing: false)

    } else {

        try Permission.location.requestAccess(whenInUseOnly: true) { status in

            status.value // .whenInUseOnly

            status.isAccuracyReducing // false

        }

    }

    

    if useSwiftConcurrency {

        await Permission.camera.checkStatus(withMicrophone: true) // (camera: .granted, microphone: .denied)

    } else {

        Permission.camera.checkStatus(withMicrophone: true) { status in

            status.camera // .granted

            status.microphone // .denied

        }

    }

} catch let error {

    error.userInfo["message"] // You must add a row with the “NSLocationWhenInUseUsageDescription” key to your app’s plist file and specify the reason why you are requesting access to location. This information will be displayed to a user.

    

    guard let error = error as? Permission.Error else {

        return

    }

    

    error.type // .missingPlistKey

}

```



Some permission types support additional features. For example, if a user allows access to his location only with reduced accuracy, you can request temporary access to full accuracy:



```swift

if useSwiftConcurrency {

    try? await Permission.location.requestTemporaryPreciseAccess(purposePlistKey: "Default") // true

} else {

    try? Permission.location.requestTemporaryPreciseAccess(purposePlistKey: "Default") { result in

        result // true

    }

}

```



Unfortunately, the ability to work with certain permission types is limited by default system API. For example, you can check the current status of a home permission only by requesting it.



### Info.plist



For each permission type you are using, Apple requires to add the corresponding string to your `Info.plist` that describes a purpose of your access requests. **PermissionWizard** can help you to find the name of a necessary plist key:



```swift

Permission.faceID.usageDescriptionPlistKey // NSFaceIDUsageDescription



Permission.health.readingUsageDescriptionPlistKey // NSHealthUpdateUsageDescription

Permission.health.writingUsageDescriptionPlistKey // NSHealthShareUsageDescription

```



If you request access to some permission using default system API but forget to edit your `Info.plist`, the app will crash. However with **PermissionWizard** the crash will not occur — `try` is just used.



### Thread Management



In some cases default system API may return a result in a different dispatch queue. To avoid a crash and instead of using `DispatchQueue.main.async`, you can ask **PermissionWizard** to invoke a completion block already in a preferred queue:



```swift

Permission.tracking.checkStatus { _ in

    // Default queue

}



Permission.tracking.checkStatus(completion: { _ in

    // DispatchQueue.main

}, forcedInvokationQueue: .main)

```



### UI Assets



If your UI needs permission type icons or localized names, you can easily get it using **PermissionWizard**:



```swift

let permission = Permission.speechRecognition.self



imageView.image = permission.getIcon(squircle: true)

label.text = permission.getLocalizedName() // Speech Recognition

```



Keep in mind that icons and localized strings are only available if the `Assets` component of **PermissionWizard** is installed (CocoaPods) or enabled (Carthage). All system languages are supported.



## Known Issues



- Local Network and Location permissions cannot be requested using async/await

- Bluetooth permission always returns `.granted` on simulators

- Local Network permission does not work on simulators



## Roadmap



- Extend support of macOS (specific permission types, native icons)

- Make the library compatible with Swift Package Manager

- Support more convenient usage in SwiftUI code



## Conclusion



You can contact me on [Telegram](https://t.me/debug45) and [LinkedIn](https://linkedin.com/in/debug45). If you find an issue, please [tell](https://github.com/debug45/PermissionWizard/issues/new) about it.



Library is released under the MIT license. The permission type icons and localized strings belong to Apple, their use is regulated by the company rules.



If **PermissionWizard** is useful for you please star this repository. Thank you! 👍