Info.plist Usage Description — 概要、NS*UsageDescriptionキーと設定方法

Info.plist Usage Descriptionとは？

Info.plist Usage Descriptionは、NS*UsageDescriptionプレフィックスを持つキーの文字列値で、iOSの保護されたリソースへのアクセスをリクエストする際のシステムダイアログのテキストを定義します。アプリが初めてユーザーの許可を必要とするAPI（例：カメラのAVCaptureDevice）を呼び出すと、iOSはこのテキストと許可/拒否ボタンを含むダイアログを表示します。

説明テキストは、開発者がシステムダイアログで制御できる唯一のものです。ダイアログのタイトル「<アプリ名>が[リソース]へのアクセスを求めています」は、リクエストされたリソースの種類に基づいてiOSが自動的に生成します。開発者はタイトル、ボタン、外観を変更できません — 説明テキストのみ変更可能です。

Usage Descriptionは、iOSの実行時許可モデルと密接に関連しています。ユーザーは1回のリクエストに対して許可を与え、後で設定から取り消すことができます。その後のリクエストではダイアログは再表示されません — アプリは許可ステータスを確認し、適切に対応する必要があります。

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キーは、アプリが写真を保存するだけで読み取らない場合に使用されます。最初のキーは読み取りアクセスを要求し、2番目は書き込み専用アクセスを要求します。

位置情報とナビゲーション

NSLocationWhenInUseUsageDescriptionキーは、アプリがアクティブなとき（画面上）に位置情報へのアクセスを提供します。NSLocationAlwaysAndWhenInUseUsageDescriptionは常時アクセスを提供します（バックグラウンドモードを含む）。常時アクセスが必要な場合、iOSは両方のキーを要求します：最初にWhenInUse、次にAlwaysです。

NSLocationTemporaryUsageDescriptionとNSLocationPreciseUsageDescriptionキーは、一時的なアクセスまたは正確な位置情報をリクエストするための追加キーです。正確な位置情報には個別の許可が必要であり、ユーザーはおおよその位置情報のみを有効にすることができます。

連絡先、カレンダー、その他のデータ

NSContactsUsageDescriptionキーは、CNContactStoreを介してユーザーの連絡先へのアクセスを提供します。NSCalendarsUsageDescriptionは、イベントの読み取りと作成のためにカレンダーへのアクセスを提供します。NSRemindersUsageDescriptionはリマインダーへのアクセスを提供します。NSBluetoothAlwaysUsageDescriptionは、バックグラウンドでのBluetoothアクセスを提供します（例：BLEデバイス用）。

NSHealthShareUsageDescriptionキーは、HealthKitデータの読み取りアクセスを提供します。NSHealthUpdateUsageDescriptionは、HealthKitへのデータ書き込みアクセスを提供します。アプリがヘルスケアデータを扱う場合、両方が必須です。AppleはHealthKitを使用するアプリを注意深く審査し、使用説明が機能と一致しない場合はアプリを拒否することがあります。

説明文の正しい作成方法

Usage Descriptionのテキストは、具体的で、真実で、簡潔でなければなりません。Appleは表現に関する推奨事項を提供し、レビュアーは機能との一致を確認します。

良い説明の構成

良い説明は3つの部分で構成されます：アプリがリソースで何をするのか、なぜユーザーにそれが必要なのか、そしてアクセスを許可することでユーザーがどのような利益を得るのか。例：「プロフィール写真を撮影してプロフィールにアップロードするため」。一般的なフレーズは避けてください：「アプリのパフォーマンスを向上させるため」はカメラが必要な理由を説明していません。

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キーが見つかりません」は、アップデート拒否の最も一般的な理由の1つです。