Photo Library Permission — الأساسيات، أنواع الوصول ومبدأ العمل

أساسيات Photo Library Permission

Photo Library Permission هو إذن نظام ينظم وصول التطبيق إلى ملفات الوسائط المخزنة على الجهاز. يغطي كلا من القراءة (عرض واختيار الصور ومقاطع الفيديو) والكتابة (حفظ ملفات جديدة في المعرض). تعتبر منصات الأجهزة المحمولة مكتبة الوسائط بيانات حساسة لأن الصور قد تحتوي على معلومات شخصية وخاصة.

على Android 13 (API 33)، قسم Google الإذن الواحد READ_EXTERNAL_STORAGE إلى ثلاثة أذونات منفصلة: READ_MEDIA_IMAGES للصور، READ_MEDIA_VIDEO لمقاطع الفيديو و READ_MEDIA_AUDIO للصوت. هذا يسمح للمستخدمين بمنح الوصول فقط إلى نوع معين من ملفات الوسائط. على iOS، بدءًا من iOS 14، يتيح PhotoKit للمستخدمين اختيار صور محددة للوصول بدلاً من فتح المكتبة بأكملها.

وفقًا لـ Counterpoint Research (2024)، أكثر من 70% من تطبيقات الأجهزة المحمولة في فئات الشبكات الاجتماعية والتواصل ومحرري الصور تطلب Photo Library Permission. في الوقت نفسه، 32% من المستخدمين يرفضون الوصول إلى المعرض إذا لم يفهموا سبب حاجة التطبيق لصورهم. توصي Apple و Google باستخدام PhotoPicker النظام لاختيار الملفات الفردية دون طلب وصول كامل.

الوصول إلى المعرض على Android

الوصول إلى المعرض على Android تغير بشكل كبير مع إصدار Android 13. بدلاً من إذن واحد READ_EXTERNAL_STORAGE، تم تقديم أذونات دقيقة لكل نوع وسائط، مما يمنح المستخدمين تحكمًا أكبر.

الأذونات على Android 13+

بدءًا من Android 13، يتم استخدام READ_MEDIA_IMAGES للوصول إلى الصور و READ_MEDIA_VIDEO للوصول إلى مقاطع الفيديو. لم يعد إذن READ_EXTERNAL_STORAGE يوفر الوصول إلى ملفات الوسائط — فهو محتفظ به فقط لقراءة الملفات غير الوسائط من التخزين المشترك. يبدو الإعلان في البيان كما يلي:

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

التوافق مع Android 12 وما دونه

للتوافق مع الإصدارات السابقة من Android 12 وما دونه، تحتاج أيضًا إلى إعلان READ_EXTERNAL_STORAGE. ومع ذلك، يتجاهل Android 13 تلقائيًا هذا الإذن عند وجود الأذونات الدقيقة الجديدة. استخدم السمة android:maxSdkVersion="32" في البيان للإذن القديم لإخفائه على الإصدارات الأحدث. هذا يمنع الطلبات الزائدة على الأجهزة التي تعمل بنظام Android 13+.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

طلب وقت التشغيل في Kotlin

يتم طلب وقت التشغيل لـ Photo Library Permission على Android من خلال Activity Result API. مثال لطلب الوصول إلى الصور:

private val photoPermissionLauncher =
    registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
    if (granted) {
        loadGalleryImages()
    } else {
        showPermissionDenied()
    }
}

fun pickPhoto() {
    val permission = if (Build.version.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        Manifest.permission.READ_MEDIA_IMAGES
    } else {
        Manifest.permission.READ_EXTERNAL_STORAGE
    }
    if (ContextCompat.checkSelfPermission(this, permission)
        == PackageManager.PERMISSION_GRANTED) {
        loadGalleryImages()
    } else {
        photoPermissionLauncher.launch(permission)
    }
}

الوصول إلى المعرض على iOS

الوصول إلى المعرض على iOS يتم إدارته من خلال إطار PhotoKit والمفاتيح NSPhotoLibraryUsageDescription و NSPhotoLibraryAddUsageDescription في Info.plist. بدءًا من iOS 14، يمكن للمستخدمين منح الوصول فقط إلى الصور المحددة (Limited Photo Library).

إعداد Info.plist

قراءة الصور من المكتبة تتطلب NSPhotoLibraryUsageDescription، بينما الكتابة (حفظ الصور) تتطلب NSPhotoLibraryAddUsageDescription. إذا كان التطبيق يحفظ الوسائط فقط ولكن لا يقرأها، فإن المفتاح الثاني كافٍ.

<key>NSPhotoLibraryUsageDescription</key>
<string>يحتاج التطبيق إلى الوصول إلى الصور لاختيار صورة الملف الشخصي ونشر اللقطات.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>يحتاج التطبيق إلى الوصول لحفظ الصور المعالجة في معرضك.</string>

الطلب في Swift

يتم طلب الوصول إلى الصور على iOS عبر PHPhotoLibrary.requestAuthorization. بدءًا من iOS 14، تشير الحالة .limited إلى أن المستخدم منح الوصول إلى مجموعة محدودة من الصور.

import PhotosUI

func requestPhotoLibraryAccess() {
    PHPhotoLibrary.requestAuthorization { status in
        DispatchQueue.main.async {
            switch status {
            case .authorized:
                self.loadPhotoLibrary()
            case .limited:
                self.loadSelectedPhotos()
            case .denied, .restricted:
                self.showSettingsAlert()
            case .notDetermined:
                break
            }
        }
    }
}

private func loadPhotoLibrary() {
    let fetchOptions = PHFetchOptions()
    fetchOptions.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: false)]
    let assets = PHAsset.fetchAssets(with: .image, options: fetchOptions)
    // معالجة نتائج الطلب
}

معالجة الوصول المحدود

الحالة .limited على iOS 14+ تعني أن المستخدم منح الوصول فقط إلى عدد قليل من الصور المحددة. يمكن للتطبيق طلب وصول موسع من خلال حوار النظام عن طريق استدعاء PHPhotoLibrary.shared().presentLimitedLibraryPicker. يُنصح بإظهار هذا الحوار فقط عندما يطلب المستخدم صراحةً ميزة تتطلب صورًا إضافية.

PhotoPicker مقابل إذن النظام

PhotoPicker هو مكون نظام لاختيار ملفات الوسائط لا يتطلب إذنًا للوصول إلى المكتبة بأكملها. بدءًا من Android 13 و iOS 14، توصي Google و Apple باستخدام PhotoPicker بدلاً من طلب Photo Library Permission إذا كان التطبيق يحتاج فقط إلى اختيار صورة أو عدة صور.

PhotoPicker على Android

على Android 13+، يسمح PhotoPicker المدمج (ActivityResultContracts.PickVisualMedia) للمستخدمين باختيار صورة أو فيديو دون منح الوصول إلى المعرض بأكمله. يتلقى التطبيق فقط URI للملفات المحددة. يعمل PhotoPicker دون إعلان أي أذونات في البيان.

private val pickMedia =
    registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
    if (uri != null) {
        // URI للملف المحدد، دون الوصول إلى المكتبة بأكملها
        showImage(uri)
    }
}

fun selectPhoto() {
    pickMedia.launch(PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly))
}

PHPicker على iOS

على iOS 14+ تم تقديم PHPickerViewController — منتقي النظام الذي لا يتطلب أيضًا الوصول إلى المكتبة بأكملها. يعمل PHPicker في عملية منفصلة وليس لديه وصول إلى مكتبة التطبيق. هذه هي الطريقة المفضلة لاختيار الصور لمعظم السيناريوهات.

import PhotosUI

func presentPhotoPicker() {
    var config = PHPickerConfiguration()
    config.selectionLimit = 1
    config.filter = .images

    let picker = PHPickerViewController(configuration: config)
    picker.delegate = self
    present(picker, animated: true)
}

متى تكون هناك حاجة إلى الإذن الكامل

PhotoPicker غير مناسب إذا كان التطبيق يحتاج إلى الوصول إلى المكتبة بأكملها للعمليات الجماعية: النسخ الاحتياطي، المزامنة السحابية، تطبيق المعرض، مدير الملفات. في هذه الحالات، تحتاج إلى طلب Photo Library Permission ومعالجة حالة الوصول المحدود (Limited). بالنسبة لنظام iOS، يجب تضمين معالجة الحالة .limited وتقديم خيار للمستخدمين لتوسيع الوصول.

أفضل ممارسات الوصول إلى المعرض

أفضل الممارسات للعمل مع Photo Library Permission تساعد في تقليل عدد الرفض والامتثال لمتطلبات الخصوصية للمنصات.

استخدم PhotoPicker افتراضيًا

لاختيار صورة أو عدة صور، استخدم PhotoPicker أو PHPicker النظام. هذه المكونات لا تتطلب أذونات وتوفر أفضل تجربة مستخدم. اطلب الوصول الكامل إلى المعرض فقط إذا كانت وظيفة التطبيق تتطلب الوصول إلى مكتبة الوسائط بأكملها. Google و Apple توصيان صراحةً بهذا النهج في توثيق المطورين.

اشرح سبب الوصول الكامل

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

اطلب فقط الأذونات الضرورية

إذا كان التطبيق يحفظ الصور فقط ولكن لا يقرأها (على سبيل المثال، محرر صور يحفظ النتيجة)، فاطلب فقط إذن الكتابة إلى المعرض. على Android، هذا هو WRITE_EXTERNAL_STORAGE (لنظام Android 12 وما دونه) أو MediaStore API بدون أذونات (لنظام Android 10+). على iOS، استخدم NSPhotoLibraryAddUsageDescription بدون NSPhotoLibraryUsageDescription.