Article

Accessing Protected Resources

Request user permission to access restricted resources by providing a purpose string that explains why you need the access.

Overview

Modern devices collect and store a wealth of sensitive information about their users. Many apps rely on this kind of data and the device hardware that generates it to do useful work. For example, a navigation app needs the user’s current GPS coordinates to locate the user on a map. But not all apps need access to all data. The same navigation app doesn’t need the user’s health history, camera interface, or Bluetooth peripherals.

Your app should access only what it needs to do its job. To support this principle, Apple’s operating systems restrict access to protected data and resources by default. Apps can request access on a case-by-case basis, providing an explanation for why they need access. The user decides whether to grant or deny the request.

Provide a Purpose String

The first time your app attempts to access a protected resource, the system prompts the user for permission. In the following example, an iOS app called MyRoute that provides directions generates a prompt requesting access to the user’s location:

Screenshot of a system-generated iOS alert view asking if the app "MyRoute" should be allowed to access location data, including a usage description message from the app’s developer.

If the user grants permission, the system remembers the user’s choice and doesn’t prompt again. If the user denies permission, the access attempt that initiated the prompt and any further attempts fail in a resource-specific way.

The system automatically generates the prompt’s title, which includes the name of your app. You supply a message called a purpose string or a usage description—in this case, “Your location is used to provide turn-by-turn directions to your destination”to indicate the reason that your app needs the access. Accurately and concisely explaining to the user why your app needs access to sensitive data, typically in one complete sentence, lets the user make an informed decision and improves the chances that they’ll grant access.

You provide a usage description by setting a string value for a resource-specific key that you add to your app’s Info.plist file. The message shown above, for example, is a string associated with the NSLocationWhenInUseUsageDescription key. Modify your Info.plist file using the property list editor built into Xcode:

Screenshot of an app’s information property list highlighting the added NSLocationWhenInUseUsageDescription key and associated string value that matches the message seen in the previous figure.

For more information about an app’s information property list, see About Information Property List Files.

The following table lists the purpose string keys for different resources, and the platforms on which they are required to gain access to the given resource.

Check for Authorization

Many system frameworks that provide access to protected resources have dedicated APIs for checking and requesting authorization to use those resources. This allows you to adjust your app’s behavior depending on the current access it has. For example, if the user denies your app permission to do something, you can remove related elements from your user interface.

Because a user can change authorization at any time using Settings, always check the authorization status of a feature before accessing it. In cases without a dedicated API, like HomeKit, be prepared to gracefully handle access failures.

The following table provides links to information about how to gain or check access to various resources from within your app.

Resource

Checking or getting access

Apple Events

When your app first attempts to control another app using Apple Events, the system presents an authorization request to the user. There’s no explicit API for requesting or testing availabilty. Be prepared to handle any access failures gracefully.

Bluetooth

Use the state property of the CBCentralManager class to check system-authorization status for using Bluetooth peripherals.

Calendar and Reminders

See Accessing the Event Store in the EventKit framework.

Camera and Microphone

See Requesting Authorization for Media Capture on iOS in the AVFoundation framework.

Contacts

See the methods in Privacy Access in the CNContactStore class.

Face ID

See Logging a User into Your App with Face ID or Touch ID in the LocalAuthentication framework.

HealthKit

See Setting Up HealthKit and Protecting User Privacy in the HealthKit framework.

HomeKit

When your app first attempts to access a property of the HMHomeManager class, the system presents an authorization request to the user. There’s no explicit API for requesting or testing availabilty. Be prepared to handle any access failures gracefully.

Location

See Choosing the Authorization Level for Location Services and Determining the Availability of Location Services.

Motion

See the methods in Determining Activity Availability in the CMMotionActivityManager class.

Music and media

See the methods in Getting the Default Media Library in the MPMediaLibrary class.

Photos

See Requesting Authorization to Access Photos in PhotoKit.

Siri

See Requesting Authorization to Use SiriKit in SiriKit.

Speech recognition

See the methods in Requesting Authorization from the User in the SFSpeechRecognizer class.

See Also

Supporting Privacy

Encrypting Your App’s Files

Protect the user’s data in iOS by encrypting it on disk.