PermissionsKit

PermissionsKit is an easy-to-use and unified Swift API for determining and requesting access to system resources that require user permission. In addition, a simple UI is included for prompting the user for permissions.

Out of the box, the following permissions are supported:

• Calendar
• Camera
• Contacts
• Location (When in Use and Always)
• Media Library
• Microphone
• Motion Activity
• Photos
• Reminders
• Speech Recognition

See this Stack Overflow answer for a list of all permissions.

Compatibility

PermissionsKit is written in Swift and supports Swift 4.2 and iOS 12.

Example

See the example app for usage.

Documentation

Docs can be generated via Jazzy and a docs target is included.

---

Installation

Recommended to use Carthage.

• Add github.com/davemess/PermissionsKit.git to your Cartfile
• Perform a carthage update
• Embed the built product in your app's embedded frameworks.

Important

Your app must define Info.plist keys for the associated permissions or it will crash when the user is prompted by the system. (See the Info.plist in PermissionsKitExample). The relevant keys are:

• NSCalendarsUsageDescription
• NSCameraUsageDescription
• NSContactsUsageDescription
• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription
• NSAppleMusicUsageDescription
• NSMicrophoneUsageDescription
• NSMotionUsageDescription
• NSPhotoLibraryUsageDescription
• NSRemindersUsageDescription
• NSSpeechRecognitionUsageDescription

---

Usage

Objectives

PermissionsKit has two objectives:

1. Standardize and unify the authorization mechanisms for the different system resources which require authorization.
2. Provide a standard UI for prompting the user for permissions.

Relevant Classes

Permission A enum value which defines the supported permission types.

PermissionController Manages access to a specific permission. Once you have access to a PermissionController instance for a specific Permission, you can query status and/or prompt the user for permission.

PermissionControllerProvider A singleton which supplies PermissionController instances for each supported Permission type.

PermissionPromptController This is a protocol which exists to make managing and prompting permissions easier. A default implementation exists for UIViewController which presents

PermissionPromptViewController This is included as a UI element for prompting users before the system dialog.

Usage Examples

You can use PermissionsKit with or without the UI component. To use without:

// Get a reference to the controller
let provider = PermissionControllerProvider.standard
let controller = provider.permissionController(.photos)

// Now you can use the controller directly to get the current status for the Photos permission.
let status = permissionStatus
switch status {
  case .unknown:
    // status is unknown, probably because the user has not been prompted
  case .permitted:
    // this permission has been granted, and you are free to use the resource
  case .denied:
    // this permission is blocked, and you should not attempt to use the resource
}

You can also use the included UI. For instance, conform your custom view controller to PermissionPromptController and you will get the built in functionality:

import PermissionsKit

class MyCustomViewController: UIViewController, PermissionPromptController {
  ...

  @IBAction func importPhotoButtonPressed(_ sender: Any) {
    let permission: Permission = .photos
    if shouldPromptForPermission(permission) {

      // This will present an animated view with user-facing messaging about the permission you are requesting. If the user accepts, the system prompt will be shown. If they deny, you should handle the denial.
      promptForPermission(permission, animated: true) { result in
        switch result {
          case .accepted:
            // The user accepted the custom UI and the system prompt. You are free to use the resource.
          case .denied(let permissionError):
            // The user denied. Check the error to find out why.
          }

      }
    }
  }

If you don't want the default UI details, you can customize what's shown by configuring a PermissionPromptProvider.

import PermissionsKit

class MyCustomPromptProvider: PermissionPromptController {

  // eg. load prompt data from a JSON file such as
  // {
  //  "title": "Camera",
  //  "reason": "We want to be able to take photos.",
  //  "icon": "camera_image",
  //  }

  func viewModel(for permission: Permission) -> PermissionPromptViewModel {
    let title = data["title"]
    let reason = data["reason"]
    let icon = UIImage(named: data["icon"])

    return PermissionPromptViewModel(icon: icon, title: title, reason: reason)
  }

---

Contributing

Definitely looking for contributors. Particularly UI designers.

License

PermissionsKit is available under the MIT license. See the LICENSE file for more info.

Credits

- Background image photo by Casey Horner on Unsplash. - Icons from Flaticon.

---

TODO

Admin

• Document public interface
• Update README with usage examples
• Versioning
• Unit Testing
• New UI!