Info.plist Usage Description — ano ito, mga key na NS*UsageDescription at setup

Ano ang Info.plist Usage Description?

Info.plist Usage Description — ay ang mga string value ng mga key na may prefix na NS*UsageDescription na tumutukoy sa text ng system dialog kapag humihiling ng access sa mga protektadong resource ng iOS. Kapag ang app ay unang tumawag ng API na nangangailangan ng pahintulot ng user (halimbawa AVCaptureDevice para sa camera), nagpapakita ang iOS ng dialog na may text na ito at mga button para sa pagpayag o pagtanggi.

Ang text ng paglalarawan ay ang tanging bagay na makokontrol ng developer sa system dialog. Ang pamagat ng dialog “Gusto ng app na makakuha ng access sa [resource]” ay awtomatikong binuo ng iOS batay sa uri ng hinihiling na resource. Hindi mababago ng developer ang pamagat, mga button, o hitsura — tanging ang text ng paliwanag.

Ang Usage Description ay malapit na nauugnay sa modelo ng runtime permissions sa iOS. Ang user ay nagbibigay ng pahintulot para sa isang hiling, na maaaring bawiin sa ibang pagkakataon sa pamamagitan ng Settings. Sa paulit-ulit na hiling, hindi ipinapakita ang dialog — dapat suriin ng app ang status ng pahintulot at tumugon nang naaayon.

Mahigpit na inirerekomenda ng Apple na banggitin sa paglalarawan ang tiyak na dahilan ng paghiling ng access. Halimbawa, “Para kumuha ng mga profile photo” ay mas mahusay kaysa “Para sa access sa camera”. Ang mga tiyak na text ay nagpapataas ng tiwala ng user at porsyento ng mga ipinagkaloob na pahintulot. Ayon sa data ng Localytics (2023), ang mga custom na paglalarawan ay nagtataas ng pagsang-ayon ng 15-25% kumpara sa mga pangkalahatang pormulasyon.

Pagkakaiba sa pagitan ng Usage Description at ATT

Huwag ipagkamali ang NS*UsageDescription sa ATT (App Tracking Transparency). Ang Usage Description ay isang hiling para sa access sa mga system resource (camera, geolokasyon, photo), habang ang ATT ay isang hiling para sa pagsubaybay (access sa IDFA). Ang ATT ay gumagamit ng hiwalay na framework na AppTrackingTransparency at key na NSUserTrackingUsageDescription, na hindi kabilang sa NS*UsageDescription.

Ang pagkakatulad nila ay pareho silang gumagamit ng system dialog na may text na hindi mababago ng app. Ang pagkakaiba ay ang Usage Description ay gumagana sa antas ng resource, habang ang ATT ay sa antas ng device identifier. Ang mga key na NS*UsageDescription ay ipinakilala sa iOS 6, ATT — sa iOS 14.5.

Ebolusyon ng mga key sa iba’t ibang bersyon ng iOS

Sa bawat paglabas ng iOS, nagdagdag ang Apple ng mga bagong protektadong resource at kaukulang key. iOS 6: contacts, kalendaryo, reminders, photo. iOS 7: mikropono. iOS 8: HomeKit, Health. iOS 10: media library, Siri. iOS 11: NFC. iOS 14: pagsubaybay (ATT). iOS 17: access sa clipboard (nangangailangan ng karagdagang kumpirmasyon).

Mahalaga: kung ang app ay gumagamit ng API na ipinakilala sa isang partikular na bersyon ng iOS, ngunit ang minimum na sinusuportahang bersyon ay mas mababa, ang key ay kinakailangan pa rin. Sinusuri ng iOS ang presensya ng key bago ang unang tawag sa API, anuman ang bersyon kung saan tumatakbo ang app.

Aling mga key na NS*UsageDescription ang kinakailangan

Ang kumpletong listahan ng mga key ay depende sa kung anong mga function ang ginagamit ng app. Suriin natin ang 14 na pangunahing key na pinakamadalas kailanganin sa mga mobile app.

Access sa multimedia

Key na NSCameraUsageDescription — kinakailangan kapag ina-access ang camera sa pamamagitan ng AVCaptureDevice o UIImagePickerController na may source na .camera. Key na NSMicrophoneUsageDescription — kapag nagre-record ng audio sa pamamagitan ng AVAudioRecorder o nagre-record ng video na may tunog. Ang parehong key ay madalas na kinakailangan nang magkasama kung ang app ay nagre-record ng video.

Key na NSPhotoLibraryUsageDescription — kapag nagbabasa ng mga photo at video mula sa media library ng user sa pamamagitan ng PHPicker o UIImagePickerController. Key na NSPhotoLibraryAddUsageDescription — kung ang app ay nagse-save lamang ng mga photo ngunit hindi binabasa ang mga ito. Ang una ay humihiling ng read access, ang pangalawa — write access lamang.

Geolokasyon at nabigasyon

Key na NSLocationWhenInUseUsageDescription — access sa geolokasyon kapag aktibo ang app (nasa screen). NSLocationAlwaysAndWhenInUseUsageDescription — access palagi (kabilang ang background). Kinakailangan ng iOS ang parehong key kung kailangan ang laging naka-on na access: una WhenInUse, pagkatapos Always.

Mga key na NSLocationTemporaryUsageDescription at NSLocationPreciseUsageDescription — karagdagang mga key para sa paghiling ng pansamantalang access o tumpak na geolokasyon. Ang tumpak na lokasyon ay nangangailangan ng hiwalay na pahintulot, at ang user ay maaari lamang i-on ang approximado.

Contacts, kalendaryo at iba pang data

Key na NSContactsUsageDescription — access sa mga contact ng user sa pamamagitan ng CNContactStore. NSCalendarsUsageDescription — access sa kalendaryo para sa pagbabasa at paggawa ng mga event. NSRemindersUsageDescription — access sa mga reminder. NSBluetoothAlwaysUsageDescription — access sa Bluetooth sa background (halimbawa para sa mga BLE device).

Key na NSHealthShareUsageDescription — access sa pagbabasa ng data ng HealthKit. NSHealthUpdateUsageDescription — access sa pagsulat ng data sa HealthKit. Pareho ay kinakailangan kung ang app ay gumagana sa larangan ng kalusugan. Maingat na sinusuri ng Apple ang mga app na gumagamit ng HealthKit at maaaring tanggihan kung ang paglalarawan ng paggamit ay hindi tumutugma sa functionality.

Paano bumalangkas ng tamang paglalarawan

Ang text sa Usage Description ay dapat tiyak, totoo at maikli. Ang Apple ay nagbibigay ng mga rekomendasyon para sa mga pormulasyon, at sinusuri ng mga moderator ang mga ito para sa pagtutugma sa functionality.

Structure ng mabuting paglalarawan

Ang mabuting paglalarawan ay binubuo ng tatlong bahagi: kung ano ang ginagawa ng app sa resource, bakit ito kailangan ng user, at anong benepisyo ang makukuha ng user mula sa pagbibigay ng access. Halimbawa: “Para kumuha ng mga profile photo at i-upload ang mga ito sa form”. Iwasan ang mga pangkalahatang parirala: “Para sa pagpapabuti ng paggana ng app” ay hindi nagpapaliwanag kung bakit kailangan ang camera.

Ipinagbabawal ng Apple ang mga nakaliligaw na paglalarawan. Kung nakasulat “Para kumuha ng mga photo” ngunit ang app ay nagre-record din ng video, ito ay maaaring ituring na panlilinlang. Maaaring tanggihan ng moderator ang app o humingi ng paliwanag. Sa iOS 17, nagdagdag ang Apple ng awtomatikong pagsusuri: ang paglalarawan ay dapat maglaman ng mga keyword na tumutugma sa hinihiling na resource.

Lokalisasyon: ang paglalarawan ay dapat isalin sa lahat ng wikang sinusuportahan ng app. Kung ang app ay available sa 10 wika, bawat Usage Description key ay dapat may mga pagsasalin sa mga file na Localizable.strings o InfoPlist.strings. Inirerekomenda ng Apple ang paggamit ng InfoPlist.strings para sa lokalisasyon ng mga key ng Info.plist.

Mga masama at mabuting halimbawa

• Masa: “Kinakailangan ang access sa camera” — hindi nagpapaliwanag kung bakit
• Mabuti: “Para sa pag-scan ng QR code sa pagbabayad” — tiyak at malinaw
• Masa: “Para sa pagtukoy ng lokasyon” — hindi tiyak
• Mabuti: “Para sa paghahanap ng pinakamalapit na restaurant sa mapa” — nagpapakita ng halaga
• Masa: “Para sa pagpapabuti ng serbisyo” — hindi nagbibigay-impormasyon
• Mabuti: “Para sa pag-upload ng mga photo sa review ng produkto” — tiyak na aksyon

Lokalisasyon sa pamamagitan ng InfoPlist.strings

Para sa lokalisasyon ng Usage Description, hindi kailangang i-duplicate ang Info.plist para sa bawat wika. Gumawa ng file na InfoPlist.strings sa bawat direktoryo ng wika at tukuyin ang mga value ng key. Awtomatikong gagamitin ng iOS ang angkop na wika sa dialog. Sinusuportahan ng Xcode ang base localization para sa Info.plist simula sa bersyon 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Para sa pag-scan ng QR code";
"NSPhotoLibraryUsageDescription" =
    "Para sa pag-upload ng mga larawan sa profile";
"NSLocationWhenInUseUsageDescription" =
    "Para sa pagpapakita ng mga kalapit na tindahan sa mapa";

Pagpapatupad: code at mga setting

Ang tamang pagpapatupad ng Usage Description ay kinabibilangan ng pagdaragdag ng mga key sa Info.plist, pagsusuri ng status ng pahintulot sa code, at paghawak ng pagtanggi.

Pagdaragdag ng mga key sa pamamagitan ng Xcode

Sa Xcode buksan ang Info.plist, ituro ang isang linya at i-click ang “+”. Ilagay ang pangalan ng key (halimbawa NSCameraUsageDescription) at tukuyin ang string ng paglalarawan. Awtomatikong kinukumpleto ng Xcode ang mga pangalan ng key, na nagbabawas ng panganib ng typo. Pagkatapos idagdag, i-rebuild ang proyekto at suriin kung lumilitaw ang key sa huling binary file.

Mahalaga: ang mga key ay case-sensitive. NSCameraUsageDescription — tama, NSCamerausagedescription — mali. Ang maling key ay binabalewala, at ang app ay mag-crash kapag tumawag ng API. Gumamit ng pagkopya mula sa dokumentasyon ng Apple o autocompletion ng Xcode upang maiwasan ang mga typo.

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

Paghawak ng pagtanggi sa access

Kung tinanggihan ng user ang access, hindi dapat muling tawagan ng app ang system dialog — ito ay imposible. Sa halip, magpakita ng impormasyong screen na may paliwanag kung paano i-on ang access sa pamamagitan ng Settings at isang button na “Buksan ang settings” (UIApplicationOpenSettingsURLString). Ang kasanayang ito ay nagpapabuti sa karanasan ng user at nagpapataas ng posibilidad na i-on ng user ang access.

Huwag magpakita ng alert na humihiling na i-on ang access kaagad pagkatapos ng pagtanggi — bigyan ang user ng pagkakataong maunawaan kung bakit maaaring kailanganin nila ang function na ito. Mas mainam na magpakita ng paliwanag kapag sinusubukang gamitin ang functionality na nangangailangan ng nasabing pahintulot. Ang UX Movement (2023) ay nagrerekomenda na magpakita ng paliwanag na screen pagkatapos ng 2-3 session mula sa pagtanggi.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Access sa \(feature)",
        message: "Payagan ang access sa Settings, "
            + "para gamitin ang feature na ito",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Buksan ang Settings",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Hindi ngayon", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Ano ang mangyayari kung hindi mo ilalagay ang Usage Description

Ang kawalan ng mandatoryong Usage Description key ay nagiging sanhi ng agarang pag-crash ng app sa unang tawag ng kaukulang API. Ito ay hindi babala ng Xcode, kundi isang runtime crash na may exception na NSInvalidArgumentException at mensahe sa console: “This app has crashed because it attempted to access privacy-sensitive data without a usage description”.

Pag-uugali sa runtime nang walang key

Sinusuri ng iOS ang presensya ng NS*UsageDescription key sa Info.plist sa unang tawag ng API para sa protektadong resource. Kung wala ang key, agad na tinatapos ng system ang app na may signal na SIGABRT. Ito ay nangyayari kahit sa mga device na may debugging — ipinapakita ng Xcode ang exception sa log, ngunit hindi ito nahuhuli ng debugger bilang breakpoint.

Ang pag-crash ay nangyayari sa mga tunay na device at simulator. Ang tanging paraan upang maiwasan ito ay idagdag ang key bago ang tawag sa API. Ang static analyzer ng Xcode ay hindi palaging nagbababala tungkol sa kawalan ng key, lalo na kung ang API ay tinatawag sa pamamagitan ng third-party na SDK. Makikita rin ng mga tester ng TestFlight ang pag-crash, na maaaring humantong sa mga negatibong review.

Espesyal na sitwasyon sa iOS 17+: Nagdagdag ang Apple ng karagdagang pagsusuri para sa access sa clipboard (UIPasteboard). Kung binabasa ng app ang clipboard nang walang tahasang aksyon ng user, nagpapakita ang iOS ng banner ng babala, kahit na mayroong Usage Description key. Para sa clipboard, hindi kinakailangan ang hiwalay na key, ngunit inirerekomenda ng Apple na bawasan ang awtomatikong pagbabasa.

Mga error sa pagsusuri ng App Store

Bukod sa runtime crash, ang kawalan ng key ay maaaring maging dahilan ng pagtanggi ng app sa moderasyon. Sinusuri ng Apple ang Info.plist sa yugto ng pagsusuri at maaaring tanggihan ang build kung makakita ito ng mga tawag sa API nang walang kaukulang key. Hindi hinaharangan ng Xcode ang pag-archive, ngunit ang App Store Connect ay maaaring magbalik ng error sa pagproseso ng binary file.

Kung hindi direktang ginagamit ng app ang resource, ngunit ginagawa ito ng third-party na SDK (halimbawa, humihiling ang analytics SDK ng IDFA), dapat pa ring idagdag ng developer ang kaukulang key. Sinusuri ng Apple ang lahat ng tawag sa API sa binary file, kabilang ang code mula sa static at dynamic na library. Ang error na “Missing Info.plist key” ay isa sa mga pinakakaraniwang dahilan ng pagtanggi ng mga update.