Photo Library Permission — podstawy, rodzaje dostępu i zasada działania

Podstawy Photo Library Permission

Photo Library Permission — to systemowe uprawnienie regulujące dostęp aplikacji do plików multimedialnych przechowywanych na urządzeniu. Obejmuje zarówno odczyt (przeglądanie i wybór zdjęć i filmów), jak i zapis (zapisywanie nowych plików do galerii). Platformy mobilne traktują bibliotekę multimediów jako dane poufne, ponieważ zdjęcia mogą zawierać informacje osobiste i wrażliwe.

Na Android 13 (API 33) Google podzielił jedno uprawnienie READ_EXTERNAL_STORAGE na trzy osobne: READ_MEDIA_IMAGES dla zdjęć, READ_MEDIA_VIDEO dla filmów i READ_MEDIA_AUDIO dla audio. Pozwala to użytkownikowi przyznać dostęp tylko do określonego typu plików multimedialnych. Na iOS, od iOS 14, PhotoKit umożliwia użytkownikowi wybór konkretnych zdjęć do udostępnienia, zamiast otwierania całej biblioteki.

Według Counterpoint Research (2024), ponad 70% aplikacji mobilnych w kategoriach mediów społecznościowych, komunikacji i edytorów zdjęć żąda Photo Library Permission. Przy tym 32% użytkowników odmawia dostępu do galerii, jeśli nie rozumieją, po co aplikacji potrzebne są ich zdjęcia. Apple i Google zalecają korzystanie z systemowego PhotoPicker do wyboru pojedynczych plików bez żądania pełnego dostępu.

Dostęp do galerii na Android

Dostęp do galerii na Android znacząco zmienił się wraz z wydaniem Android 13. Zamiast jednego uprawnienia READ_EXTERNAL_STORAGE pojawiły się szczegółowe uprawnienia dla każdego typu plików multimedialnych, co daje użytkownikowi większą kontrolę.

Uprawnienia na Android 13+

Od Android 13 do dostępu do zdjęć używa się READ_MEDIA_IMAGES, a do filmów — READ_MEDIA_VIDEO. Uprawnienie READ_EXTERNAL_STORAGE nie zapewnia już dostępu do plików multimedialnych — pozostało tylko do odczytu plików innych niż multimedia z pamięci współdzielonej. Deklaracja w manifeście wygląda następująco:

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

Zgodność z Android 12 i starszymi

Dla wstecznej zgodności z Android 12 i starszymi należy również zadeklarować READ_EXTERNAL_STORAGE. Jednak Android 13 automatycznie ignoruje to uprawnienie przy obecności nowych szczegółowych. Użyj w manifeście atrybutu android:maxSdkVersion="32" dla starego uprawnienia, aby ukryć je na nowych wersjach. Zapobiega to zbędnemu żądaniu na urządzeniach z Android 13+.

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

Żądanie w czasie wykonania w Kotlin

Żądanie w czasie wykonania dla Photo Library Permission na Android wykonuje się przez Activity Result API. Przykład żądania dostępu do obrazów:

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

Dostęp do galerii na iOS

Dostęp do galerii na iOS jest zarządzany przez framework PhotoKit i klucze NSPhotoLibraryUsageDescription oraz NSPhotoLibraryAddUsageDescription w Info.plist. Od iOS 14 użytkownik może przyznać dostęp tylko do wybranych zdjęć (Limited Photo Library).

Konfiguracja Info.plist

Do odczytu zdjęć z biblioteki wymagany jest NSPhotoLibraryUsageDescription, do zapisu (zapisywanie zdjęć) — NSPhotoLibraryAddUsageDescription. Jeśli aplikacja tylko zapisuje multimedia, ale ich nie odczytuje, wystarczy drugi klucz.

<key>NSPhotoLibraryUsageDescription</key>
<string>Aplikacja potrzebuje dostępu do zdjęć, aby wybrać zdjęcie profilowe i publikować zdjęcia.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Aplikacja potrzebuje dostępu, aby zapisać przetworzone zdjęcia w Twojej galerii.</string>

Żądanie w Swift

Żądanie dostępu do zdjęć na iOS wykonuje się przez PHPhotoLibrary.requestAuthorization. Od iOS 14 status .limited oznacza, że użytkownik przyznał dostęp do ograniczonego zestawu zdjęć.

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)
    // Praca z wynikami żądania
}

Obsługa Limited Access

Status .limited na iOS 14+ oznacza, że użytkownik przyznał dostęp tylko do kilku wybranych zdjęć. Aplikacja może zażądać rozszerzenia dostępu przez systemowy dialog, wywołując PHPhotoLibrary.shared().presentLimitedLibraryPicker. Zaleca się pokazywanie tego dialogu tylko gdy użytkownik wyraźnie zażąda funkcji, do której potrzebne są dodatkowe zdjęcia.

PhotoPicker a uprawnienie systemowe

PhotoPicker — to systemowy komponent wyboru plików multimedialnych, który nie wymaga uprawnienia do dostępu do całej biblioteki. Od Android 13 i iOS 14, Google i Apple zalecają korzystanie z PhotoPicker zamiast żądania Photo Library Permission, jeśli aplikacja potrzebuje tylko wybrać jedno lub kilka zdjęć.

PhotoPicker na Android

Na Android 13+ wbudowany PhotoPicker (ActivityResultContracts.PickVisualMedia) pozwala użytkownikowi wybrać zdjęcie lub film bez przyznawania dostępu do całej galerii. Aplikacja otrzymuje tylko URI wybranych plików. PhotoPicker działa bez deklarowania jakichkolwiek uprawnień w manifeście.

private val pickMedia =
    registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
    if (uri != null) {
        // URI wybranego pliku, bez dostępu do całej biblioteki
        showImage(uri)
    }
}

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

PHPicker na iOS

Na iOS 14+ pojawił się PHPickerViewController — systemowy picker, który również nie wymaga dostępu do całej biblioteki. PHPicker działa w osobnym procesie i nie ma dostępu do biblioteki aplikacji. Jest to preferowany sposób wyboru zdjęć w większości scenariuszy.

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

Kiedy potrzebne jest pełne uprawnienie

PhotoPicker nie jest odpowiedni, jeśli aplikacja wymaga dostępu do całej biblioteki do operacji masowych: tworzenie kopii zapasowej, synchronizacja z chmurą, aplikacja-galeria, menedżer plików. W takich przypadkach należy żądać Photo Library Permission i obsługiwać przypadek ograniczonego dostępu (Limited). Dla iOS obowiązkowe jest dodanie obsługi statusu .limited i zaproponowanie użytkownikowi rozszerzenia dostępu.

Najlepsze praktyki dostępu do galerii

Najlepsze praktyki pracy z Photo Library Permission pomagają zmniejszyć liczbę odmów i spełniać wymagania platform dotyczące ochrony prywatności.

Używaj PhotoPicker domyślnie

Do wyboru jednego lub kilku zdjęć używaj systemowego PhotoPicker lub PHPicker. Te komponenty nie wymagają uprawnień i zapewniają najlepsze doświadczenie użytkownika. Pełne uprawnienie do dostępu do galerii żądaj tylko wtedy, gdy funkcjonalność aplikacji wymaga dostępu do całej biblioteki multimediów. Google i Apple wyraźnie zalecają takie podejście w dokumentacji dla programistów.

Wyjaśniaj powód pełnego dostępu

Jeśli aplikacja rzeczywiście potrzebuje pełnego dostępu do galerii, pokaż wstępny ekran z wyjaśnieniem. Wyjaśnij, po co potrzebne są wszystkie zdjęcia, a nie tylko jedno. Na przykład aplikacja do tworzenia kopii zapasowej powinna wyjaśnić, że będzie skanować wszystkie pliki multimedialne w celu utworzenia kopii. Pre-permission screen jest szczególnie ważny na iOS ze względu na mechanizm Limited Access.

Żądaj tylko niezbędnych uprawnień

Jeśli aplikacja tylko zapisuje zdjęcia, ale ich nie odczytuje (np. edytor zdjęć, który zapisuje wynik), żądaj tylko uprawnienia do zapisu w galerii. Na Android jest to WRITE_EXTERNAL_STORAGE (dla Android 12 i starszych) lub MediaStore API bez uprawnień (dla Android 10+). Na iOS używaj NSPhotoLibraryAddUsageDescription bez NSPhotoLibraryUsageDescription.