Latest 1.1.2
Homepage https://github.com/bqlin/PermissionScope-ObjC
License MIT MIT License

Copyright (c) 2018

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Platforms ios 8.0, requires ARC
Authors

PermissionScope is no longer supported. Please use an alternative if you need updates for newer iOS 10 and 11 APIs!

PermissionScope

Platform: iOS 8+Language: Swift 3
Carthage compatible
Cocoapods compatible
License: MIT

Installation
Usage
Customization
Known bugs
Issues
License

Inspired by (but unrelated to) Periscope‘s permission control, PermissionScope is a Swift framework for intelligently requesting permissions from users. It contains not only a simple UI to request permissions but also a unified permissions API that can tell you the status of any given system permission or easily request them.

Some examples of multiple permissions requests, a single permission and the denied alert.

permissionscope gif

PermissionScope gives you space to explain your reasons for requesting permissions and allows users to tackle the system dialogs at their own pace. It presents a straightforward permissions design and is flexible enough to fit in to most UIKit-based apps.

Best of all, PermissionScope detects when your app’s permissions have been denied by a user and gives them an easy prompt to go into the system settings page to modify these permissions.

Supported permissions:

  • Notifications
  • Location (WhileInUse, Always)
  • Contacts
  • Events
  • Microphone
  • Camera
  • Photos
  • Reminders
  • Bluetooth
  • Motion

compatibility

PermissionScope requires iOS 8+, compatible with both Swift 3 and Objective-C based projects.

For Swift 2.x support, please use the swift2 branch or the 1.0.2 release version. This branch was up-to-date on 9/6/16 but is not being maintained. All future efforts will go towards Swift 3 development.

installation

Installation for Carthage is simple enough:

github "nickoneill/PermissionScope" ~> 1.0

As for Cocoapods, use this to get the latest release:

use_frameworks!

pod 'PermissionScope'

And import PermissionScope in the files you’d like to use it.

dialog usage

The simplest implementation displays a list of permissions and is removed when all of them have satisfactory access.

class ViewController: UIViewController {
    let pscope = PermissionScope()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set up permissions
        pscope.addPermission(ContactsPermission(),
            message: "We use this to stealrnyour friends")
        pscope.addPermission(NotificationsPermission(notificationCategories: nil),
            message: "We use this to send yournspam and love notes")
        pscope.addPermission(LocationWhileInUsePermission(),
            message: "We use this to trackrnwhere you live")

    // Show dialog with callbacks
        pscope.show({ finished, results in
            print("got results (results)")
        }, cancelled: { (results) -> Void in
            print("thing was cancelled")
        })   
    }
}

The permissions view will automatically show if there are permissions to approve and will take no action if permissions are already granted. It will automatically hide when all permissions have been approved.

If you’re attempting to block access to a screen in your app without permissions (like, say, the broadcast screen in Periscope), you should watch for the cancel closure and take an appropriate action for your app.

customization

You can easily change the colors, label and buttons fonts with PermissionScope by modifying any of these properties:

Field Type Comment
headerLabel UILabel Header UILabel with the message "Hey, listen!" by default.
bodyLabel UILabel Header UILabel with the message "We need a couple thingsrnbefore you get started." by default.
closeButtonTextColor UIColor Color for the close button’s text color.
permissionButtonTextColor UIColor Color for the permission buttons’ text color.
permissionButtonBorderColor UIColor Color for the permission buttons’ border color.
buttonFont UIFont Font used for all the UIButtons
labelFont UIFont Font used for all the UILabels
closeButton UIButton Close button. By default in the top right corner.
closeOffset CGSize Offset used to position the Close button.
authorizedButtonColor UIColor Color used for permission buttons with authorized status
unauthorizedButtonColor UIColor? Color used for permission buttons with unauthorized status. By default, inverse of authorizedButtonColor.
permissionButtonΒorderWidth CGFloat Border width for the permission buttons.
permissionButtonCornerRadius CGFloat Corner radius for the permission buttons.
permissionLabelColor UIColor Color for the permission labels’ text color.
contentView UIView Dialog’s content view

In addition, the default behavior for tapping the background behind the dialog is to cancel the dialog (which calls the cancel closure you can provide on show). You can change this behavior with backgroundTapCancels during init.

If you’d like more control over the button text for a particular permission, you can use a .strings file for your intended language and override them that way. Please get in touch if you’d like to contribute a localization file for another language!

unified permissions API

PermissionScope also has an abstracted API for getting the state for a given permission and requesting permissions if you need to do so outside of the normal dialog UI. Think of it as a unified iOS permissions API that can provide some features that even Apple does not (such as detecting denied notification permissions).

switch PermissionScope().statusContacts() {
case .Unknown:
    // ask
    PermissionScope().requestContacts()
case .Unauthorized, .Disabled:
    // bummer
    return
case .Authorized:
    // thanks!
    return
}

calling request* methods directly

Normally PermissionScope is used to walk users through necessary permissions before they’re allowed to do something in your app. Sometimes you may wish to instead call into the various request* permissions-seeking methods of PermissionScope directly, from your own UI.

To call these methods directly, you must first set the viewControllerForAlerts method to your current UIViewController, in case PermissionScope needs to present some alerts to the user for denied or disabled permissions:

let pscope = PermissionScope()
pscope.viewControllerForAlerts = self

You will probably also want to set the onAuthChange, onCancel, and onDisabledOrDenied closures, which are called at the appropriate times when the request* methods are finished, otherwise you won’t know when the work has been completed.

pscope.onAuthChange = { (finished, results) in
    println("Request was finished with results (results)")
    if results[0].status == .Authorized {
        println("They've authorized the use of notifications")
        UIApplication.sharedApplication().registerForRemoteNotifications()
    }
}
pscope.onCancel = { results in
    println("Request was cancelled with results (results)")
}
pscope.onDisabledOrDenied = { results in
    println("Request was denied or disabled with results (results)")
}

And then you might call it when the user toggles a switch:

@IBAction func notificationsChanged(sender: UISwitch) {
    if sender.on {
        // turn on notifications
        if PermissionScope().statusNotifications() == .Authorized {
            UIApplication.sharedApplication().registerForRemoteNotifications()
        } else {
            pscope.requestNotifications()
        }
    } else {
        // turn off notifications
    }

If you’re also using PermissionScope in the traditional manner, don’t forget to set viewControllerForAlerts back to it’s default, the instance of PermissionScope. The easiest way to do this is to set it explicitly before you call a request* method, and then reset it in your closures.

pscope.viewControllerForAlerts = pscope as UIViewController

PermissionScope registers user notification settings, not remote notifications

Users will get the prompt to enable notifications when using PermissionScope but it’s up to you to watch for results in your app delegate’s didRegisterUserNotificationSettings and then register for remote notifications independently. This won’t alert the user again. You’re still responsible for handling the shipment of user notification settings off to your push server.

extra requirements for permissions

location

You must set these Info.plist keys for location to work

Trickiest part of implementing location permissions? You must implement the proper key in your Info.plist file with a short description of how your app uses location info (shown in the system permissions dialog). Without this, trying to get location permissions will just silently fail. Software!

Use NSLocationAlwaysUsageDescription or NSLocationWhenInUseUsageDescription where appropriate for your app usage. You can specify which of these location permissions you wish to request with .LocationAlways or .LocationInUse while configuring PermissionScope.

bluetooth

The NSBluetoothPeripheralUsageDescription key in the Info.plist specifying a short description of why your app needs to act as a bluetooth peripheral in the background is optional.

However, enabling background-modes in the capabilities section and checking the acts as a bluetooth LE accessory checkbox is required.

known bugs

  • ITC app rejection with the following reason: "This app attempts to access privacy-sensitive data without a usage description". (#194)

Solution: TBD

  • When the user is taken to the Settings.app, if any of the app’s permissions are changed (whilst the app was in the background), the app will crash. (#160)

Solution: None. Works as intended by the OS.

  • Link "Show me" does not work on denied a permission (#61)

Solution: Run your app without the debugger.

  • When using Carthage, the following error occurs: Module file was created by an older version of the compiler.

Solution: Use the --no-use-binaries flag (e.g: carthage update --no-use-binaries).

license

PermissionScope uses the MIT license. Please file an issue if you have any questions or if you’d like to share how you’re using this tool.

Latest podspec

{
    "name": "PermissionScopeObjC",
    "version": "1.1.2",
    "summary": "PermissionScope u539fu9879u76ee Objective-C u590du523bu7248",
    "description": "PermissionScope u539fu9879u76ee Objective-C u590du523bu7248u3002u4f7fu7528 Objective-C u91cdu5199u4e86u4e00u904d PermissionScope u5e93uff0cu4fddu7559u4e86u539fu6709u7684u63a5u53e3u4e0eu6ce8u91cau3002u4f9du7136u53efu4ee5u4f7fu7528u539fu6709u9879u76eeu7684u793au4f8b Demo u8c03u7528u590du523bu7248u3002",
    "homepage": "https://github.com/bqlin/PermissionScope-ObjC",
    "screenshots": "http://raquo.net/images/permissionscope.gif",
    "license": {
        "type": "MIT",
        "text": "    MIT LicensennCopyright (c) 2018nnPermission is hereby granted, free of charge, to any person obtaining a copynof this software and associated documentation files (the "Software"), to dealnin the Software without restriction, including without limitation the rightsnto use, copy, modify, merge, publish, distribute, sublicense, and/or sellncopies of the Software, and to permit persons to whom the Software isnfurnished to do so, subject to the following conditions:nnThe above copyright notice and this permission notice shall be included in allncopies or substantial portions of the Software.nnTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORnIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEnAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERnLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THEnSOFTWARE.n"
    },
    "authors": {
        "bqlin": "[email protected]"
    },
    "requires_arc": true,
    "platforms": {
        "ios": "8.0"
    },
    "source": {
        "git": "https://github.com/bqlin/PermissionScope-ObjC.git",
        "tag": "1.1.2"
    },
    "source_files": "PermissionScope-ObjC/PermissionScopeObjC/PermissionScope/*.{h,m}",
    "xcconfig": {
        "OTHER_LDFLAGS": "-ObjC"
    }
}

Pin It on Pinterest

Share This