وصف استخدام Info.plist — ما هو، مفاتيح NS*UsageDescription والإعدادات

ما هو وصف استخدام Info.plist؟

وصف استخدام Info.plist هي قيم نصية للمفاتيح ذات البادئة NS*UsageDescription التي تحدد نص حوار النظام عند طلب الوصول إلى الموارد المحمية في iOS. عندما يستدعي التطبيق لأول مرة API يتطلب إذن المستخدم (مثل AVCaptureDevice للكاميرا)، يعرض iOS حواراً بهذا النص مع أزرار السماح أو الرفض.

نص الوصف هو الشيء الوحيد الذي يمكن للمطور التحكم به في حوار النظام. عنوان الحوار «<اسم التطبيق> يريد الوصول إلى [المورد]» يتم إنشاؤه تلقائياً بواسطة iOS بناءً على نوع المورد المطلوب. لا يمكن للمطور تغيير العنوان أو الأزرار أو المظهر — فقط النص التوضيحي.

يرتبط وصف الاستخدام ارتباطاً وثيقاً بنموذج الأذونات في وقت التشغيل في iOS. يمنح المستخدم الإذن لطلب واحد، ويمكن إلغاؤه لاحقاً عبر الإعدادات. عند الطلب التالي، لا يظهر الحوار مرة أخرى — يجب على التطبيق التحقق من حالة الإذن والرد وفقاً لذلك.

توصي Apple بشدة بتحديد سبب محدد لطلب الوصول في الوصف. على سبيل المثال، «لالتقاط صور الملف الشخصي» أفضل من «للوصول إلى الكاميرا». النصوص المحددة تزيد من ثقة المستخدم ومعدل منح الإذن. وفقاً لـ Localytics (2023)، تزيد الأوصاف المخصصة من الموافقة بنسبة 15-25% مقارنة بالصياغات العامة.

الفرق بين وصف الاستخدام وATT

لا تخلط بين NS*UsageDescription وATT (شفافية تتبع التطبيقات). وصف الاستخدام هو طلب الوصول إلى موارد النظام (الكاميرا، الموقع الجغرافي، الصور)، بينما ATT هو طلب التتبع (الوصول إلى IDFA). يستخدم ATT إطار عمل منفصل AppTrackingTransparency والمفتاح NSUserTrackingUsageDescription، والذي لا ينتمي إلى NS*UsageDescription.

القاسم المشترك بينهما هو أن كليهما يستخدم حوار نظام مع نص لا يمكن للتطبيق تعديله. الفرق هو أن وصف الاستخدام يعمل على مستوى الموارد، بينما 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: الوصول إلى الحافظة (يتطلب تأكيداً إضافياً).

هام: إذا كان التطبيق يستخدم API تم تقديمه في إصدار معين من iOS ولكن الإصدار الأدنى المدعوم أقل، فإن المفتاح لا يزال إلزامياً. يتحقق iOS من وجود المفتاح قبل أول استدعاء للـ API، بغض النظر عن الإصدار الذي يعمل عليه التطبيق.

مفاتيح NS*UsageDescription الإلزامية

تعتمد القائمة الكاملة للمفاتيح على الوظائف التي يستخدمها التطبيق. دعنا نستعرض المفاتيح الـ 14 الرئيسية الأكثر طلباً في تطبيقات الجوال.

الوصول إلى الوسائط المتعددة

المفتاح NSCameraUsageDescription إلزامي عند الوصول إلى الكاميرا عبر AVCaptureDevice أو UIImagePickerController بمصدر .camera. المفتاح 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 وقد ترفض التطبيق إذا كان وصف الاستخدام لا يتطابق مع الوظيفة.

كيفية صياغة الوصف بشكل صحيح

يجب أن يكون النص في وصف الاستخدام محدداً وصادقاً وموجزاً. تقدم Apple توصيات بشأن الصياغة، ويتحقق المراجعون من تطابقها مع الوظيفة.

هيكل الوصف الجيد

يتكون الوصف الجيد من ثلاثة أجزاء: ما يفعله التطبيق بالمورد بالضبط، ولماذا يحتاجه المستخدم، وما الفائدة التي يحصل عليها المستخدم من منح الوصول. مثال: «لالتقاط صور الملف الشخصي وتحميلها إلى ملفك الشخصي». تجنب العبارات العامة: «لتحسين أداء التطبيق» لا يشرح سبب الحاجة للكاميرا.

تمنع Apple الأوصاف المضللة. إذا كان مكتوباً «لالتقاط الصور» ولكن التطبيق يسجل فيديو أيضاً، فقد يعتبر ذلك خادعاً. قد يرفض المراجع التطبيق أو يطلب توضيحات. في iOS 17، أضافت Apple تحققاً تلقائياً: يجب أن يحتوي الوصف على كلمات رئيسية تتوافق مع المورد المطلوب.

التوطين: يجب ترجمة الوصف إلى جميع اللغات التي يدعمها التطبيق. إذا كان التطبيق متاحاً بـ 10 لغات، يجب أن يكون لكل مفتاح وصف استخدام ترجمات في ملفات Localizable.strings أو InfoPlist.strings. توصي Apple باستخدام InfoPlist.strings لتوطين مفاتيح Info.plist.

أمثلة سيئة وجيدة

• سيء: «يحتاج الوصول إلى الكاميرا» — لا يشرح لماذا
• جيد: «لمسح رموز QR عند الدفع» — محدد وواضح
• سيء: «لتحديد الموقع» — غامض
• جيد: «للبحث عن المطاعم القريبة على الخريطة» — يظهر القيمة
• سيء: «لتحسين الخدمة» — غير مفيد
• جيد: «لتحميل الصور إلى مراجعة المنتج» — إجراء محدد

التوطين عبر InfoPlist.strings

لتوطين وصف الاستخدام، لا تحتاج إلى تكرار Info.plist لكل لغة. أنشئ ملف InfoPlist.strings في كل دليل لغة وحدد قيم المفاتيح. سيستبدل iOS تلقائياً اللغة الصحيحة في الحوار. يدعم Xcode التوطين الأساسي لـ Info.plist بدءاً من الإصدار 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "لمسح رموز QR";
"NSPhotoLibraryUsageDescription" =
    "لتحميل الصور إلى الملف الشخصي";
"NSLocationWhenInUseUsageDescription" =
    "لعرض المتاجر القريبة على الخريطة";

التنفيذ: الكود والإعدادات

يتضمن التنفيذ الصحيح لوصف الاستخدام إضافة المفاتيح إلى 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)
}

ماذا يحدث إذا لم تحدد وصف الاستخدام

يؤدي غياب مفتاح وصف الاستخدام الإلزامي إلى تعطل فوري للتطبيق عند أول استدعاء للـ API المقابل. هذا ليس تحذيراً من Xcode، بل تعطل في وقت التشغيل مع NSInvalidArgumentException ورسالة في وحدة التحكم: «تعطل هذا التطبيق لأنه حاول الوصول إلى بيانات حساسة للخصوصية بدون وصف استخدام».

السلوك في وقت التشغيل بدون المفتاح

يتحقق iOS من وجود مفتاح NS*UsageDescription في Info.plist عند أول استدعاء API لمورد محمي. إذا كان المفتاح مفقوداً، ينهي النظام التطبيق فوراً بإشارة SIGABRT. يحدث هذا حتى على أجهزة التصحيح — يعرض Xcode الاستثناء في السجل، لكن المصحح لا يلتقطه كنقطة توقف.

يتكرر التعطل على الأجهزة الحقيقية والمحاكي. الطريقة الوحيدة لتجنبه هي إضافة المفتاح قبل استدعاء API. لا يحذر المحلل الثابت في Xcode دائماً من غياب المفتاح، خاصة إذا تم استدعاء API عبر SDK تابعة لجهات خارجية. سيرى مختبرو TestFlight التعطل أيضاً، مما قد يؤدي إلى مراجعات سلبية.

حالة خاصة مع iOS 17+: أضافت Apple فحصاً إضافياً للوصول إلى الحافظة (UIPasteboard). إذا قرأ التطبيق الحافظة دون إجراء صريح من المستخدم، يعرض iOS لافتة تحذير، حتى إذا كان مفتاح وصف الاستخدام موجوداً. لا تتطلب الحافظة مفتاحاً منفصلاً، لكن Apple توصي بتقليل القراءة التلقائية.

أخطاء مراجعة App Store

بالإضافة إلى التعطل في وقت التشغيل، قد يتسبب غياب المفتاح في رفض التطبيق أثناء المراجعة. تتحقق Apple من Info.plist في مرحلة المراجعة وقد ترفض البنية إذا اكتشفت استدعاءات API بدون مفاتيح مقابلة. لا يمنع Xcode الأرشفة، لكن App Store Connect قد يعيد خطأ عند معالجة الملف الثنائي.

إذا كان التطبيق لا يستخدم المورد مباشرة ولكن SDK تابعة لجهة خارجية تفعل ذلك (على سبيل المثال، SDK تحليلات تطلب IDFA)، يجب على المطور إضافة المفتاح المقابل مع ذلك. تتحقق Apple من جميع استدعاءات API في الملف الثنائي، بما في ذلك الكود من المكتبات الثابتة والديناميكية. خطأ «مفتاح Info.plist مفقود» هو أحد الأسباب الأكثر شيوعاً لرفض التحديثات.