Info.plist Usage Description — nó là gì, các khóa NS*UsageDescription và thiết lập

Info.plist Usage Description là gì?

Info.plist Usage Description là các giá trị chuỗi của các khóa có tiền tố NS*UsageDescription xác định văn bản của hộp thoại hệ thống khi yêu cầu truy cập vào các tài nguyên được bảo vệ của iOS. Khi ứng dụng lần đầu tiên gọi một API yêu cầu quyền của người dùng (ví dụ: AVCaptureDevice cho máy ảnh), iOS hiển thị một hộp thoại với văn bản này và các nút cho phép/từ chối.

Văn bản mô tả là thứ duy nhất mà nhà phát triển có thể kiểm soát trong hộp thoại hệ thống. Tiêu đề hộp thoại “ muốn truy cập [tài nguyên]” được iOS tự động tạo dựa trên loại tài nguyên được yêu cầu. Nhà phát triển không thể thay đổi tiêu đề, nút hoặc giao diện — chỉ có văn bản giải thích.

Usage Description liên quan chặt chẽ đến mô hình quyền runtime trong iOS. Người dùng cấp quyền cho một yêu cầu, có thể bị thu hồi sau đó qua Cài đặt. Khi yêu cầu tiếp theo, hộp thoại sẽ không hiển thị lại — ứng dụng phải kiểm tra trạng thái quyền và phản hồi phù hợp.

Apple đặc biệt khuyến nghị chỉ định lý do cụ thể cho yêu cầu truy cập trong mô tả. Ví dụ: “Để chụp ảnh hồ sơ” tốt hơn “Để truy cập máy ảnh”. Văn bản cụ thể làm tăng niềm tin của người dùng và tỷ lệ cấp quyền. Theo Localytics (2023), mô tả tùy chỉnh làm tăng sự đồng ý lên 15–25% so với các diễn đạt chung chung.

Sự khác biệt giữa Usage Description và ATT

Đừng nhầm lẫn NS*UsageDescription với ATT (App Tracking Transparency). Usage Description là yêu cầu truy cập vào tài nguyên hệ thống (máy ảnh, định vị, ảnh), trong khi ATT là yêu cầu theo dõi (truy cập IDFA). ATT sử dụng một framework riêng AppTrackingTransparency và khóa NSUserTrackingUsageDescription, không thuộc NS*UsageDescription.

Điểm chung là cả hai đều sử dụng hộp thoại hệ thống với văn bản mà ứng dụng không thể sửa đổi. Sự khác biệt là Usage Description hoạt động ở cấp tài nguyên, trong khi ATT hoạt động ở cấp định danh thiết bị. Các khóa NS*UsageDescription được giới thiệu trong iOS 6, ATT — trong iOS 14.5.

Sự phát triển của các khóa qua các phiên bản iOS

Mỗi bản phát hành iOS, Apple đều thêm các tài nguyên được bảo vệ mới và các khóa tương ứng. iOS 6: danh bạ, lịch, lời nhắc, ảnh. iOS 7: micrô. iOS 8: HomeKit, Sức khỏe. iOS 10: thư viện phương tiện, Siri. iOS 11: NFC. iOS 14: theo dõi (ATT). iOS 17: truy cập bảng nhớ tạm (cần xác nhận thêm).

Quan trọng: nếu ứng dụng sử dụng API được giới thiệu trong một phiên bản iOS cụ thể nhưng phiên bản hỗ trợ tối thiểu thấp hơn, khóa vẫn là bắt buộc. iOS kiểm tra sự hiện diện của khóa trước lần gọi API đầu tiên, bất kể ứng dụng đang chạy trên phiên bản nào.

Các khóa NS*UsageDescription bắt buộc

Danh sách đầy đủ các khóa phụ thuộc vào chức năng mà ứng dụng sử dụng. Hãy xem xét 14 khóa chính thường được yêu cầu nhất trong các ứng dụng di động.

Truy cập phương tiện

Khóa NSCameraUsageDescription là bắt buộc khi truy cập máy ảnh qua AVCaptureDevice hoặc UIImagePickerController với nguồn .camera. Khóa NSMicrophoneUsageDescription cần thiết khi ghi âm qua AVAudioRecorder hoặc khi quay video có âm thanh. Cả hai khóa thường cần cùng nhau nếu ứng dụng quay video.

Khóa NSPhotoLibraryUsageDescription được sử dụng khi đọc ảnh và video từ thư viện phương tiện của người dùng qua PHPicker hoặc UIImagePickerController. Khóa NSPhotoLibraryAddUsageDescription được sử dụng nếu ứng dụng chỉ lưu ảnh mà không đọc chúng. Khóa đầu tiên yêu cầu quyền đọc, khóa thứ hai — chỉ quyền ghi.

Định vị và dẫn đường

Khóa NSLocationWhenInUseUsageDescription cung cấp quyền truy cập định vị khi ứng dụng đang hoạt động (trên màn hình). NSLocationAlwaysAndWhenInUseUsageDescription cung cấp quyền truy cập mọi lúc (bao gồm chế độ nền). iOS yêu cầu cả hai khóa nếu cần truy cập liên tục: đầu tiên là WhenInUse, sau đó là Always.

Các khóa NSLocationTemporaryUsageDescription và NSLocationPreciseUsageDescription là các khóa bổ sung để yêu cầu truy cập tạm thời hoặc định vị chính xác. Vị trí chính xác yêu cầu quyền riêng biệt và người dùng chỉ có thể bật vị trí gần đúng.

Danh bạ, lịch và dữ liệu khác

Khóa NSContactsUsageDescription cung cấp quyền truy cập vào danh bạ của người dùng qua CNContactStore. NSCalendarsUsageDescription cung cấp quyền truy cập lịch để đọc và tạo sự kiện. NSRemindersUsageDescription cung cấp quyền truy cập vào lời nhắc. NSBluetoothAlwaysUsageDescription cung cấp quyền truy cập Bluetooth trong nền (ví dụ: cho thiết bị BLE).

Khóa NSHealthShareUsageDescription cung cấp quyền đọc dữ liệu HealthKit. NSHealthUpdateUsageDescription cung cấp quyền ghi dữ liệu vào HealthKit. Cả hai đều bắt buộc nếu ứng dụng làm việc với dữ liệu sức khỏe. Apple kiểm tra kỹ lưỡng các ứng dụng sử dụng HealthKit và có thể từ chối ứng dụng nếu mô tả sử dụng không khớp với chức năng.

Cách viết mô tả đúng cách

Văn bản trong Usage Description phải cụ thể, trung thực và ngắn gọn. Apple đưa ra các khuyến nghị về cách diễn đạt và người kiểm duyệt xác minh sự phù hợp với chức năng.

Cấu trúc của một mô tả tốt

Một mô tả tốt bao gồm ba phần: ứng dụng làm gì với tài nguyên, tại sao người dùng cần nó và lợi ích gì người dùng nhận được khi cấp quyền truy cập. Ví dụ: “Để chụp ảnh hồ sơ và tải lên hồ sơ của bạn.” Tránh các cụm từ chung chung: “Để cải thiện hiệu suất ứng dụng” không giải thích tại sao cần máy ảnh.

Apple cấm các mô tả gây hiểu lầm. Nếu ghi “Để chụp ảnh” nhưng ứng dụng cũng quay video, điều này có thể bị coi là lừa dối. Người kiểm duyệt có thể từ chối ứng dụng hoặc yêu cầu làm rõ. Trong iOS 17, Apple đã thêm xác thực tự động: mô tả phải chứa các từ khóa tương ứng với tài nguyên được yêu cầu.

Bản địa hóa: mô tả phải được dịch sang tất cả các ngôn ngữ mà ứng dụng hỗ trợ. Nếu ứng dụng có sẵn bằng 10 ngôn ngữ, mỗi khóa Usage Description phải có bản dịch trong tệp Localizable.strings hoặc InfoPlist.strings. Apple khuyến nghị sử dụng InfoPlist.strings để bản địa hóa các khóa Info.plist.

Ví dụ xấu và tốt

• Xấu: “Cần quyền truy cập máy ảnh” — không giải thích lý do
• Tốt: “Để quét mã QR khi thanh toán” — cụ thể và rõ ràng
• Xấu: “Để xác định vị trí” — mơ hồ
• Tốt: “Để tìm nhà hàng gần đó trên bản đồ” — thể hiện giá trị
• Xấu: “Để cải thiện dịch vụ” — không có thông tin
• Tốt: “Để tải ảnh lên đánh giá sản phẩm” — hành động cụ thể

Bản địa hóa qua InfoPlist.strings

Để bản địa hóa Usage Description, bạn không cần nhân bản Info.plist cho mỗi ngôn ngữ. Tạo tệp InfoPlist.strings trong mỗi thư mục ngôn ngữ và chỉ định giá trị khóa. iOS sẽ tự động sử dụng đúng ngôn ngữ trong hộp thoại. Xcode hỗ trợ bản địa hóa cơ sở cho Info.plist từ phiên bản 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Để quét mã QR";
"NSPhotoLibraryUsageDescription" =
    "Để tải ảnh lên hồ sơ";
"NSLocationWhenInUseUsageDescription" =
    "Để hiển thị cửa hàng gần đó trên bản đồ";

Triển khai: mã nguồn và cài đặt

Việc triển khai đúng cách Usage Description bao gồm thêm khóa vào Info.plist, kiểm tra trạng thái quyền trong mã nguồn và xử lý từ chối.

Thêm khóa qua Xcode

Trong Xcode, mở Info.plist, di chuột qua một hàng và nhấp vào “+”. Nhập tên khóa (ví dụ: NSCameraUsageDescription) và chỉ định chuỗi mô tả. Xcode tự động hoàn thành tên khóa, giảm rủi ro sai chính tả. Sau khi thêm, xây dựng lại dự án và xác minh rằng khóa xuất hiện trong tệp nhị phân cuối cùng.

Quan trọng: các khóa phân biệt chữ hoa chữ thường. NSCameraUsageDescription đúng, NSCamerausagedescription là sai. Khóa không đúng sẽ bị bỏ qua và ứng dụng sẽ bị sập khi gọi API. Sử dụng bản sao từ tài liệu Apple hoặc tính năng tự động hoàn thành của Xcode để tránh sai chính tả.

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)")
        }
    }
}

Xử lý từ chối truy cập

Nếu người dùng từ chối truy cập, ứng dụng không nên gọi lại hộp thoại hệ thống — điều đó là không thể. Thay vào đó, hãy hiển thị màn hình thông tin giải thích cách bật quyền truy cập qua Cài đặt, với nút “Mở Cài đặt” (UIApplicationOpenSettingsURLString). Thực hành này cải thiện trải nghiệm người dùng và khả năng người dùng bật quyền truy cập.

Đừng hiển thị cảnh báo yêu cầu bật quyền truy cập ngay sau khi từ chối — hãy cho người dùng thời gian để hiểu tại sao họ có thể cần chức năng này. Tốt hơn nên hiển thị lời giải thích khi cố gắng sử dụng chức năng yêu cầu quyền này. UX Movement (2023) khuyến nghị hiển thị màn hình giải thích sau 2–3 phiên kể từ khi từ chối.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Truy cập vào \(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)
}

Điều gì xảy ra nếu không chỉ định Usage Description

Việc thiếu khóa Usage Description bắt buộc gây ra sập ứng dụng ngay lập tức ở lần gọi API đầu tiên tương ứng. Đây không phải là cảnh báo của Xcode, mà là sập runtime với NSInvalidArgumentException và thông báo trong bảng điều khiển: “Ứng dụng này đã bị sập vì nó cố gắng truy cập dữ liệu nhạy cảm về quyền riêng tư mà không có mô tả sử dụng.”

Hành vi runtime khi thiếu khóa

iOS kiểm tra sự hiện diện của khóa NS*UsageDescription trong Info.plist ở lần gọi API đầu tiên cho một tài nguyên được bảo vệ. Nếu thiếu khóa, hệ điều hành ngay lập tức kết thúc ứng dụng bằng tín hiệu SIGABRT. Điều này xảy ra ngay cả trên thiết bị gỡ lỗi — Xcode hiển thị ngoại lệ trong nhật ký, nhưng trình gỡ lỗi không bắt nó như điểm dừng.

Sự cố này tái tạo trên thiết bị thật và trình mô phỏng. Cách duy nhất để tránh là thêm khóa trước khi gọi API. Trình phân tích tĩnh của Xcode không phải lúc nào cũng cảnh báo về việc thiếu khóa, đặc biệt nếu API được gọi qua SDK bên thứ ba. Người thử nghiệm TestFlight cũng sẽ thấy sự cố, điều này có thể dẫn đến đánh giá tiêu cực.

Tình huống đặc biệt với iOS 17+: Apple đã thêm kiểm tra bổ sung cho quyền truy cập bảng nhớ tạm (UIPasteboard). Nếu ứng dụng đọc bảng nhớ tạm mà không có hành động rõ ràng của người dùng, iOS hiển thị biểu ngữ cảnh báo, ngay cả khi khóa Usage Description có mặt. Bảng nhớ tạm không yêu cầu khóa riêng, nhưng Apple khuyến nghị giảm thiểu việc đọc tự động.

Lỗi khi xét duyệt App Store

Ngoài sự cố runtime, việc thiếu khóa có thể dẫn đến từ chối ứng dụng trong quá trình xét duyệt. Apple kiểm tra Info.plist ở giai đoạn xét duyệt và có thể từ chối bản dựng nếu phát hiện các lời gọi API mà không có khóa tương ứng. Xcode không chặn việc lưu trữ, nhưng App Store Connect có thể trả về lỗi khi xử lý tệp nhị phân.

Nếu ứng dụng không sử dụng trực tiếp tài nguyên nhưng SDK bên thứ ba làm điều đó (ví dụ: SDK phân tích yêu cầu IDFA), nhà phát triển vẫn phải thêm khóa tương ứng. Apple kiểm tra tất cả các lời gọi API trong tệp nhị phân, bao gồm mã từ thư viện tĩnh và động. Lỗi “Thiếu khóa Info.plist” là một trong những nguyên nhân phổ biến nhất dẫn đến từ chối cập nhật.