Info.plist Usage Description — 개념, NS*UsageDescription 키 및 설정

Info.plist Usage Description이란?

Info.plist Usage Description은 NS*UsageDescription 접두사가 있는 키의 문자열 값으로, iOS의 보호된 리소스에 대한 액세스를 요청할 때 시스템 대화상자의 텍스트를 정의합니다. 앱이 처음으로 사용자 권한이 필요한 API(예: 카메라의 AVCaptureDevice)를 호출하면 iOS는 이 텍스트와 허용/거부 버튼이 있는 대화상자를 표시합니다.

설명 텍스트는 개발자가 시스템 대화상자에서 제어할 수 있는 유일한 것입니다. 대화상자 제목 “<앱 이름>이(가) [리소스]에 액세스하려고 합니다”는 요청된 리소스 유형에 따라 iOS가 자동으로 생성합니다. 개발자는 제목, 버튼 또는 모양을 변경할 수 없으며 설명 텍스트만 변경할 수 있습니다.

Usage Description은 iOS의 런타임 권한 모델과 밀접하게 관련됩니다. 사용자는 한 번의 요청에 대해 권한을 부여하며, 나중에 설정을 통해 취소할 수 있습니다. 이후 요청에서는 대화상자가 다시 표시되지 않으며 앱은 권한 상태를 확인하고 적절히 대응해야 합니다.

Apple은 설명에 액세스 요청의 구체적인 이유를 명시할 것을 강력히 권장합니다. 예를 들어 “프로필 사진 촬영용”이 “카메라 액세스용”보다 좋습니다. 구체적인 텍스트는 사용자 신뢰와 허용률을 높입니다. Localytics(2023)에 따르면 사용자 정의 설명은 일반적인 표현에 비해 동의율이 15~25% 증가합니다.

Usage Description과 ATT의 차이

NS*UsageDescription을 ATT(App Tracking Transparency)와 혼동하지 마세요. Usage Description은 시스템 리소스(카메라, 위치 정보, 사진)에 대한 액세스 요청이고, ATT는 추적(IDFA 액세스)에 대한 요청입니다. ATT는 별도 프레임워크인 AppTrackingTransparency와 NSUserTrackingUsageDescription 키를 사용하며, 이는 NS*UsageDescription에 속하지 않습니다.

공통점은 둘 다 앱이 수정할 수 없는 텍스트가 포함된 시스템 대화상자를 사용한다는 점입니다. 차이점은 Usage Description은 리소스 수준에서 작동하는 반면 ATT는 기기 식별자 수준에서 작동한다는 것입니다. NS*UsageDescription 키는 iOS 6에서 도입되었고 ATT는 iOS 14.5에서 도입되었습니다.

iOS 버전별 키의 진화

각 iOS 릴리스와 함께 Apple은 새로운 보호 리소스와 해당 키를 추가했습니다. iOS 6: 연락처, 캘린더, 미리 알림, 사진. iOS 7: 마이크. iOS 8: HomeKit, 건강. iOS 10: 미디어 라이브러리, Siri. iOS 11: NFC. iOS 14: 추적(ATT). iOS 17: 클립보드 액세스(추가 확인 필요).

중요: 앱이 특정 iOS 버전에서 도입된 API를 사용하지만 최소 지원 버전이 더 낮은 경우에도 키는 여전히 필수입니다. iOS는 앱이 실행 중인 버전에 관계없이 첫 번째 API 호출 전에 키의 존재를 확인합니다.

필수 NS*UsageDescription 키

키의 전체 목록은 앱이 사용하는 기능에 따라 다릅니다. 모바일 앱에서 가장 일반적으로 필요한 14가지 주요 키를 살펴보겠습니다.

미디어 액세스

NSCameraUsageDescription 키는 AVCaptureDevice 또는 .camera 소스의 UIImagePickerController를 통해 카메라에 액세스할 때 필수입니다. NSMicrophoneUsageDescription 키는 AVAudioRecorder를 통해 오디오를 녹음하거나 사운드와 함께 비디오를 촬영할 때 필요합니다. 앱이 비디오를 녹화하는 경우 두 키가 함께 필요한 경우가 많습니다.

NSPhotoLibraryUsageDescription 키는 PHPicker 또는 UIImagePickerController를 통해 사용자의 미디어 라이브러리에서 사진과 비디오를 읽을 때 사용됩니다. NSPhotoLibraryAddUsageDescription 키는 앱이 사진을 저장만 하고 읽지 않는 경우에 사용됩니다. 첫 번째는 읽기 액세스를 요청하고 두 번째는 쓰기 전용 액세스를 요청합니다.

위치 정보 및 내비게이션

NSLocationWhenInUseUsageDescription 키는 앱이 활성 상태(화면에 표시됨)일 때 위치 정보 액세스를 제공합니다. NSLocationAlwaysAndWhenInUseUsageDescription은 항상 액세스를 제공합니다(백그라운드 모드 포함). 항상 액세스가 필요한 경우 iOS는 두 키를 모두 요구합니다: 먼저 WhenInUse, 그다음 Always.

NSLocationTemporaryUsageDescription 및 NSLocationPreciseUsageDescription 키는 임시 액세스 또는 정확한 위치 정보를 요청하기 위한 추가 키입니다. 정확한 위치에는 별도의 권한이 필요하며 사용자는 대략적인 위치만 활성화할 수 있습니다.

연락처, 캘린더 및 기타 데이터

NSContactsUsageDescription 키는 CNContactStore를 통해 사용자의 연락처에 액세스할 수 있도록 합니다. NSCalendarsUsageDescription은 이벤트 읽기 및 생성을 위한 캘린더 액세스를 제공합니다. NSRemindersUsageDescription은 미리 알림에 대한 액세스를 제공합니다. NSBluetoothAlwaysUsageDescription은 백그라운드에서 Bluetooth 액세스를 제공합니다(예: BLE 기기).

NSHealthShareUsageDescription 키는 HealthKit 데이터 읽기 액세스를 제공합니다. NSHealthUpdateUsageDescription은 HealthKit에 데이터 쓰기 액세스를 제공합니다. 앱이 건강 데이터를 다루는 경우 둘 다 필수입니다. Apple은 HealthKit을 사용하는 앱을 신중히 검토하며 사용 설명이 기능과 일치하지 않으면 앱을 거부할 수 있습니다.

설명을 올바르게 작성하는 방법

Usage Description의 텍스트는 구체적이고, 사실에 기반하며, 간결해야 합니다. Apple은 표현에 대한 권장 사항을 제공하며 검토자는 기능과의 일치를 확인합니다.

좋은 설명의 구성

좋은 설명은 세 부분으로 구성됩니다: 앱이 리소스로 정확히 무엇을 하는지, 사용자에게 그것이 왜 필요한지, 그리고 액세스를 허용함으로써 사용자가 어떤 이점을 얻는지. 예: “프로필 사진을 촬영하고 프로필에 업로드하기 위해.” 일반적인 문구는 피하세요: “앱 성능 향상을 위해”는 카메라가 필요한 이유를 설명하지 않습니다.

Apple은 오해의 소지가 있는 설명을 금지합니다. “사진 촬영용”이라고 되어 있지만 앱이 비디오도 녹화하는 경우 기만적인 것으로 간주될 수 있습니다. 검토자는 앱을 거부하거나 설명을 요청할 수 있습니다. iOS 17에서 Apple은 자동 검증을 추가했습니다: 설명은 요청된 리소스에 해당하는 키워드를 포함해야 합니다.

현지화: 설명은 앱이 지원하는 모든 언어로 번역되어야 합니다. 앱을 10개 언어로 제공하는 경우 각 Usage Description 키는 Localizable.strings 또는 InfoPlist.strings 파일에 번역이 있어야 합니다. Apple은 Info.plist 키의 현지화를 위해 InfoPlist.strings 사용을 권장합니다.

나쁜 예와 좋은 예

• 나쁨: “카메라 액세스 필요” — 이유를 설명하지 않음
• 좋음: “결제 시 QR 코드 스캔용” — 구체적이고 명확함
• 나쁨: “위치 확인용” — 모호함
• 좋음: “지도에서 근처 레스토랑 찾기용” — 가치를 보여줌
• 나쁨: “서비스 개선용” — 정보 부족
• 좋음: “제품 리뷰에 사진 업로드용” — 구체적인 작업

InfoPlist.strings를 통한 현지화

Usage Description을 현지화하기 위해 언어별로 Info.plist를 복제할 필요는 없습니다. 각 언어 디렉토리에 InfoPlist.strings 파일을 만들고 키 값을 지정합니다. iOS는 대화상자를 표시할 때 자동으로 올바른 언어를 사용합니다. Xcode는 버전 14부터 Info.plist에 대한 기본 현지화를 지원합니다.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "QR 코드 스캔용";
"NSPhotoLibraryUsageDescription" =
    "프로필에 이미지 업로드용";
"NSLocationWhenInUseUsageDescription" =
    "지도에 가까운 매장 표시용";

구현: 코드 및 설정

Usage Description의 올바른 구현에는 Info.plist에 키 추가, 코드에서 권한 상태 확인, 거부 처리 등이 포함됩니다.

Xcode를 통한 키 추가

Xcode에서 Info.plist를 열고 행 위로 마우스를 가져간 다음 “+”를 클릭합니다. 키 이름(예: NSCameraUsageDescription)을 입력하고 설명 문자열을 지정합니다. Xcode가 키 이름을 자동 완성하여 오타 위험을 줄입니다. 추가한 후 프로젝트를 재빌드하고 최종 바이너리에 키가 표시되는지 확인합니다.

중요: 키는 대소문자를 구분합니다. NSCameraUsageDescription은 올바르고 NSCamerausagedescription은 오류입니다. 잘못된 키는 무시되며 API 호출 시 앱이 충돌합니다. Apple 문서에서 복사하거나 Xcode 자동 완성을 사용하여 오타를 방지하세요.

import AVFoundation
import Photos

final class PermissionManager {
    static func checkCameraPermission() {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        switch status {
        case .notDetermined:
            AVCaptureDevice.requestAccess(for: .video) { granted in
                print("Camera access: \(granted)")
            }
        case .denied:
            print("Camera access denied")
        case .authorized:
            print("Camera access authorized")
        @unknown default:
            break
        }
    }

    static func requestPhotoLibraryAccess() {
        PHPhotoLibrary.requestAuthorization { status in
            print("Photo library status: \(status.rawValue)")
        }
    }
}

액세스 거부 처리

사용자가 액세스를 거부한 경우 앱이 시스템 대화상자를 다시 호출해서는 안 됩니다 — 불가능합니다. 대신 설정을 통해 액세스를 활성화하는 방법을 설명하는 정보 화면을 표시하고 “설정 열기” 버튼(UIApplicationOpenSettingsURLString)을 제공합니다. 이 방법은 사용자 경험과 사용자가 액세스를 활성화할 가능성을 향상시킵니다.

거부 직후 액세스 활성화를 요청하는 알림을 표시하지 마세요 — 사용자가 이 기능이 필요한 이유를 이해할 시간을 주세요. 이 권한이 필요한 기능을 사용하려고 할 때 설명을 표시하는 것이 좋습니다. UX Movement(2023)는 거부 후 2~3세션 후에 설명 화면을 표시할 것을 권장합니다.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "접근 권한: \(feature)",
        message: "Allow access in Settings, "
            + "to use this feature",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Open Settings",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Not now", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Usage Description을 지정하지 않을 경우

필수 Usage Description 키가 없으면 해당 API를 처음 호출할 때 앱이 즉시 충돌합니다. 이는 Xcode 경고가 아니라 NSInvalidArgumentException과 콘솔 메시지 “이 앱은 사용 설명 없이 개인 정보 보호에 민감한 데이터에 액세스하려고 시도했기 때문에 충돌했습니다”를 동반한 런타임 충돌입니다.

키가 없는 경우 런타임 동작

iOS는 보호된 리소스에 대한 첫 번째 API 호출 시 Info.plist에서 NS*UsageDescription 키의 존재를 확인합니다. 키가 없으면 OS가 SIGABRT 신호로 앱을 즉시 종료합니다. 이는 디버그 기기에서도 발생합니다 — Xcode는 로그에 예외를 표시하지만 디버거는 중단점으로 잡지 않습니다.

충돌은 실제 기기와 시뮬레이터에서 재현됩니다. 이를 방지하는 유일한 방법은 API를 호출하기 전에 키를 추가하는 것입니다. Xcode의 정적 분석기는 특히 타사 SDK를 통해 API가 호출되는 경우 키 누락에 대해 항상 경고하지 않습니다. TestFlight 테스터도 충돌을 보게 되며 부정적인 리뷰로 이어질 수 있습니다.

iOS 17+의 특별 상황: Apple은 클립보드 액세스(UIPasteboard)에 대한 추가 확인을 도입했습니다. 앱이 사용자의 명시적 조작 없이 클립보드를 읽는 경우 Usage Description 키가 있더라도 iOS는 경고 배너를 표시합니다. 클립보드에는 별도의 키가 필요하지 않지만 Apple은 자동 읽기를 최소화할 것을 권장합니다.

App Store 검토 오류

런타임 충돌 외에도 키 누락은 검토 중 앱 거부의 원인이 될 수 있습니다. Apple은 검토 단계에서 Info.plist를 확인하고 해당 키 없이 API 호출이 감지되면 빌드를 거부할 수 있습니다. Xcode는 보관을 차단하지 않지만 App Store Connect는 바이너리 처리 시 오류를 반환할 수 있습니다.

앱이 리소스를 직접 사용하지 않지만 타사 SDK가 사용하는 경우(예: 분석 SDK가 IDFA를 요청) 개발자는 여전히 해당 키를 추가해야 합니다. Apple은 정적 및 동적 라이브러리의 코드를 포함하여 바이너리의 모든 API 호출을 확인합니다. “Info.plist 키 누락” 오류는 업데이트 거부의 가장 일반적인 원인 중 하나입니다.