The MetaMap iOS SDK requires specific iOS permissions to access device features necessary for identity verification. These permissions must be declared in your app’s Info.plist file.
Failing to add these permissions will cause the app to crash when the SDK attempts to access the corresponding features. iOS requires usage description strings for all sensitive permissions.
Required Permissions
Camera Permission
Required for capturing photos of identity documents and selfies.
<key>NSCameraUsageDescription</key>
<string>MetaMap needs access to your Camera</string>
Photo Library Permission
Required for accessing and uploading images from the user’s photo gallery.
<key>NSPhotoLibraryUsageDescription</key>
<string>MetaMap needs access to your media library</string>
Microphone Permission
Required for voice liveness verification and video recording with audio.
<key>NSMicrophoneUsageDescription</key>
<string>MetaMap needs access to your Microphone</string>
Location Permissions
Required for location-based verification and fraud prevention. You need to include all three location permission keys:
<key>NSLocationWhenInUseUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
Complete Info.plist Configuration
Add all required permissions to your Info.plist file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- Other keys -->
<!-- MetaMap Required Permissions -->
<key>NSCameraUsageDescription</key>
<string>MetaMap needs access to your Camera</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>MetaMap needs access to your media library</string>
<key>NSMicrophoneUsageDescription</key>
<string>MetaMap needs access to your Microphone</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>MetaMap will use your location information to provide best possible verification experience.</string>
<!-- Other keys -->
</dict>
</plist>
Customizing Permission Descriptions
You can customize the usage description strings to better match your app’s branding and tone:
<key>NSCameraUsageDescription</key>
<string>We need camera access to verify your identity by capturing photos of your ID and face.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library so you can upload existing photos of your documents.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need microphone access for voice verification to ensure your identity security.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to prevent fraud and provide a secure verification experience.</string>
Adding Permissions in Xcode
Method 1: Using Xcode’s Info Tab
- Select your project in the Project Navigator
- Select your app target
- Go to the “Info” tab
- Click the ”+” button to add new entries
- Search for and add each permission key
- Enter the usage description in the “Value” column
Method 2: Editing Info.plist Directly
- Locate
Info.plist in your project
- Right-click and select “Open As” > “Source Code”
- Add the permission keys and descriptions
- Save the file
Runtime Permission Handling
While adding permissions to Info.plist is required, the MetaMap SDK handles requesting permissions at runtime. However, you can check permission status in your app:
Checking Camera Permission
import AVFoundation
func checkCameraPermission() {
switch AVCaptureDevice.authorizationStatus(for: .video) {
case .authorized:
print("Camera access granted")
case .notDetermined:
AVCaptureDevice.requestAccess(for: .video) { granted in
print("Camera access: \(granted)")
}
case .denied, .restricted:
print("Camera access denied")
// Show alert to guide user to settings
@unknown default:
break
}
}
Checking Photo Library Permission
import Photos
func checkPhotoLibraryPermission() {
let status = PHPhotoLibrary.authorizationStatus()
switch status {
case .authorized, .limited:
print("Photo library access granted")
case .notDetermined:
PHPhotoLibrary.requestAuthorization { newStatus in
print("Photo library access: \(newStatus == .authorized)")
}
case .denied, .restricted:
print("Photo library access denied")
@unknown default:
break
}
}
Checking Microphone Permission
import AVFoundation
func checkMicrophonePermission() {
switch AVAudioSession.sharedInstance().recordPermission {
case .granted:
print("Microphone access granted")
case .denied:
print("Microphone access denied")
case .undetermined:
AVAudioSession.sharedInstance().requestRecordPermission { granted in
print("Microphone access: \(granted)")
}
@unknown default:
break
}
}
Checking Location Permission
import CoreLocation
class LocationPermissionManager: NSObject, CLLocationManagerDelegate {
let locationManager = CLLocationManager()
override init() {
super.init()
locationManager.delegate = self
}
func checkLocationPermission() {
let status = locationManager.authorizationStatus
switch status {
case .authorizedWhenInUse, .authorizedAlways:
print("Location access granted")
case .notDetermined:
locationManager.requestWhenInUseAuthorization()
case .denied, .restricted:
print("Location access denied")
@unknown default:
break
}
}
func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
print("Location authorization changed: \(manager.authorizationStatus)")
}
}
Guiding Users to Settings
If a permission is denied, guide users to app settings:
import UIKit
func showPermissionDeniedAlert(for permission: String) {
let alert = UIAlertController(
title: "Permission Required",
message: "\(permission) access is required for identity verification. Please enable it in Settings.",
preferredStyle: .alert
)
alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
alert.addAction(UIAlertAction(title: "Settings", style: .default) { _ in
if let settingsURL = URL(string: UIApplication.openSettingsURLString) {
UIApplication.shared.open(settingsURL)
}
})
// Present alert from your view controller
// viewController.present(alert, animated: true)
}
Best Practices
- Clear Descriptions: Write clear, user-friendly permission descriptions that explain why each permission is needed
- Localization: Localize permission descriptions for better user experience in different regions
- Pre-flight Checks: Check permission status before launching MetaMap SDK to provide better user guidance
- Graceful Handling: Handle permission denials gracefully and guide users to enable them
- Minimal Permissions: Only request permissions when they’re actually needed
Troubleshooting
App Crashes When Accessing Camera
If your app crashes immediately when trying to access the camera, verify that NSCameraUsageDescription is properly added to your Info.plist.
Permission Dialog Not Showing
- Ensure the permission key is spelled correctly in Info.plist
- Clean build folder (⇧⌘K) and rebuild
- Delete the app from device/simulator and reinstall
Location Permission Not Working
- Make sure all three location permission keys are added
- Check that you’re requesting the correct authorization level in code
- Verify location services are enabled on the device
Testing Permissions
Test your permission implementation:
- Fresh Install: Test on a device without your app installed
- Permission Reset: Reset permissions in device settings
- Different States: Test granted, denied, and not-determined states
- Background Access: Test location permissions with app in background
// Reset permissions for testing (simulator only)
// Run in Terminal:
// xcrun simctl privacy booted reset all com.yourcompany.yourapp
The MetaMap SDK handles the actual permission requests at runtime. Your responsibility is to declare these permissions in Info.plist with appropriate descriptions.
