Photo Library Permission — مبانی، انواع دسترسی و اصل کار

مبانی Photo Library Permission

Photo Library Permission — مجوز سیستمی است که دسترسی برنامه به فایل‌های رسانه‌ای ذخیره شده در دستگاه را تنظیم می‌کند. هم خواندن (مشاهده و انتخاب عکس و ویدیو) و هم نوشتن (ذخیره فایل‌های جدید در گالری) را پوشش می‌دهد. پلتفرم‌های موبایل کتابخانه رسانه را به عنوان داده محرمانه در نظر می‌گیرند، زیرا عکس‌ها ممکن است حاوی اطلاعات شخصی و حساس باشند.

در Android 13 (API 33) گوگل مجوز واحد READ_EXTERNAL_STORAGE را به سه مجوز جداگانه تقسیم کرد: READ_MEDIA_IMAGES برای عکس‌ها، READ_MEDIA_VIDEO برای ویدیوها و READ_MEDIA_AUDIO برای صدا. این به کاربر اجازه می‌دهد فقط به نوع خاصی از فایل‌های رسانه‌ای دسترسی دهد. در iOS، از iOS 14 به بعد، PhotoKit به کاربر امکان می‌دهد عکس‌های مشخصی را برای دسترسی انتخاب کند، نه اینکه کل کتابخانه را باز کند.

بر اساس Counterpoint Research (2024)، بیش از 70٪ از برنامه‌های موبایل در دسته‌بندی شبکه‌های اجتماعی، ارتباطات و ویرایشگرهای عکس Photo Library Permission را درخواست می‌کنند. در عین حال، 32٪ از کاربران در صورتی که متوجه نشوند چرا برنامه به عکس‌هایشان نیاز دارد، دسترسی به گالری را رد می‌کنند. اپل و گوگل توصیه می‌کنند برای انتخاب فایل‌های جداگانه بدون درخواست دسترسی کامل از 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 به بعد، گوگل و اپل توصیه می‌کنند به جای درخواست Photo Library Permission از PhotoPicker استفاده شود، اگر برنامه فقط نیاز به انتخاب یک یا چند عکس دارد.

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 معرفی شد — یک picker سیستم که همچنین نیازی به دسترسی به کل کتابخانه ندارد. 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 سیستم استفاده کنید. این کامپوننت‌ها نیازی به مجوز ندارند و بهترین تجربه کاربری را فراهم می‌کنند. مجوز کامل دسترسی به گالری را فقط در صورتی درخواست کنید که عملکرد برنامه نیاز به دسترسی به کل کتابخانه رسانه دارد. گوگل و اپل به صراحت این رویکرد را در مستندات توسعه‌دهندگان توصیه می‌کنند.

دلیل دسترسی کامل را توضیح دهید

اگر برنامه واقعاً به دسترسی کامل به گالری نیاز دارد، یک صفحه مقدماتی با توضیح نشان دهید. توضیح دهید که چرا همه عکس‌ها لازم هستند، نه فقط یکی. به عنوان مثال، یک برنامه پشتیبان‌گیری باید توضیح دهد که برای ایجاد یک کپی، تمام فایل‌های رسانه‌ای را اسکن می‌کند. Pre-permission screen به دلیل مکانیزم Limited Access در iOS بسیار مهم است.

فقط مجوزهای لازم را درخواست کنید

اگر برنامه فقط عکس‌ها را ذخیره می‌کند اما آنها را نمی‌خواند (مثلاً ویرایشگر عکس که نتیجه را ذخیره می‌کند)، فقط مجوز نوشتن در گالری را درخواست کنید. در Android این WRITE_EXTERNAL_STORAGE (برای Android 12 و پایین‌تر) یا MediaStore API بدون مجوز (برای Android 10+) است. در iOS از NSPhotoLibraryAddUsageDescription بدون NSPhotoLibraryUsageDescription استفاده کنید.