Required Permissions

Configure Info.plist permissions required by MetaMap iOS SDK

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

1. Select your project in the Project Navigator
2. Select your app target
3. Go to the “Info” tab
4. Click the ”+” button to add new entries
5. Search for and add each permission key
6. Enter the usage description in the “Value” column

Method 2: Editing Info.plist Directly

1. Locate Info.plist in your project
2. Right-click and select “Open As” > “Source Code”
3. Add the permission keys and descriptions
4. 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

1. Clear Descriptions: Write clear, user-friendly permission descriptions that explain why each permission is needed
2. Localization: Localize permission descriptions for better user experience in different regions
3. Pre-flight Checks: Check permission status before launching MetaMap SDK to provide better user guidance
4. Graceful Handling: Handle permission denials gracefully and guide users to enable them
5. 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:

1. Fresh Install: Test on a device without your app installed
2. Permission Reset: Reset permissions in device settings
3. Different States: Test granted, denied, and not-determined states
4. 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.