🔮 PermissionWizard

Читать на русском

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 16 and macOS 13 Ventura
🖥 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 12 / macOS 10.15 Catalina
• Xcode 14
• Swift 5.5

Installation

CocoaPods

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

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. ⚠️

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

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

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!

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 an iOS 14 user allows access to his location only with reduced accuracy, you can request temporary access to full accuracy:

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:

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:

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:

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
• Music permission does not work on simulators with iOS 12

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 and LinkedIn. If you find an issue, please tell 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! 👍