Photo Library Permission — conceitos básicos, tipos de acesso e princípio de funcionamento

Conceitos Básicos de Photo Library Permission

Photo Library Permission é uma permissão do sistema que regula o acesso de um aplicativo aos arquivos de mídia armazenados no dispositivo. Abrange tanto a leitura (visualizar e selecionar fotos e vídeos) quanto a escrita (salvar novos arquivos na galeria). As plataformas móveis consideram a biblioteca de mídia como dados sensíveis porque as fotos podem conter informações pessoais e privadas.

No Android 13 (API 33), o Google dividiu a permissão única READ_EXTERNAL_STORAGE em três separadas: READ_MEDIA_IMAGES para fotos, READ_MEDIA_VIDEO para vídeos e READ_MEDIA_AUDIO para áudio. Isso permite que os usuários concedam acesso apenas a um tipo específico de arquivo de mídia. No iOS, a partir do iOS 14, o PhotoKit permite que os usuários selecionem fotos específicas para acesso em vez de abrir toda a biblioteca.

De acordo com Counterpoint Research (2024), mais de 70% dos aplicativos móveis nas categorias de redes sociais, comunicação e editores de fotos solicitam Photo Library Permission. Ao mesmo tempo, 32% dos usuários negam acesso à galeria se não entenderem por que o aplicativo precisa de suas fotos. A Apple e o Google recomendam usar o PhotoPicker do sistema para selecionar arquivos individuais sem solicitar acesso total.

Acesso à Galeria no Android

O acesso à galeria no Android mudou significativamente com o lançamento do Android 13. Em vez de uma única permissão READ_EXTERNAL_STORAGE, foram introduzidas permissões granulares para cada tipo de mídia, dando aos usuários mais controle.

Permissões no Android 13+

A partir do Android 13, READ_MEDIA_IMAGES é usado para acesso a fotos e READ_MEDIA_VIDEO para acesso a vídeos. A permissão READ_EXTERNAL_STORAGE não fornece mais acesso a arquivos de mídia — é mantida apenas para ler arquivos não relacionados a mídia do armazenamento compartilhado. A declaração no manifesto é assim:

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

Compatibilidade com Android 12 e Versões Anteriores

Para compatibilidade reversa com Android 12 e versões anteriores, você também precisa declarar READ_EXTERNAL_STORAGE. No entanto, o Android 13 ignora automaticamente essa permissão quando as novas granulares estão presentes. Use o atributo android:maxSdkVersion="32" no manifesto para a permissão antiga ocultá-la em versões mais recentes. Isso evita solicitações redundantes em dispositivos com Android 13+.

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

Solicitação em Tempo de Execução em Kotlin

A solicitação em tempo de execução para Photo Library Permission no Android é realizada através da Activity Result API. Exemplo para solicitar acesso a imagens:

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

Acesso à Galeria no iOS

O acesso à galeria no iOS é gerenciado através do framework PhotoKit e das chaves NSPhotoLibraryUsageDescription e NSPhotoLibraryAddUsageDescription no Info.plist. A partir do iOS 14, os usuários podem conceder acesso apenas a fotos selecionadas (Limited Photo Library).

Configuração do Info.plist

A leitura de fotos da biblioteca requer NSPhotoLibraryUsageDescription, enquanto a escrita (salvar fotos) requer NSPhotoLibraryAddUsageDescription. Se o aplicativo apenas salva mídia mas não a lê, a segunda chave é suficiente.

<key>NSPhotoLibraryUsageDescription</key>
<string>O aplicativo precisa de acesso às fotos para selecionar uma imagem de perfil e publicar instantâneos.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>O aplicativo precisa de acesso para salvar fotos processadas em sua galeria.</string>

Solicitação em Swift

A solicitação de acesso a fotos no iOS é realizada via PHPhotoLibrary.requestAuthorization. A partir do iOS 14, o status .limited indica que o usuário concedeu acesso a um conjunto limitado de fotos.

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)
    // Gerenciamento dos resultados da solicitação
}

Gerenciamento de Acesso Limitado

O status .limited no iOS 14+ significa que o usuário concedeu acesso apenas a algumas fotos selecionadas. O aplicativo pode solicitar acesso estendido através de um diálogo do sistema chamando PHPhotoLibrary.shared().presentLimitedLibraryPicker. Recomenda-se mostrar este diálogo apenas quando o usuário solicitar explicitamente um recurso que exija fotos adicionais.

PhotoPicker vs Permissão do Sistema

PhotoPicker é um componente do sistema para selecionar arquivos de mídia que não requer permissão para acessar toda a biblioteca. A partir do Android 13 e iOS 14, Google e Apple recomendam usar o PhotoPicker em vez de solicitar Photo Library Permission se o aplicativo precisar apenas selecionar uma ou várias fotos.

PhotoPicker no Android

No Android 13+, o PhotoPicker integrado (ActivityResultContracts.PickVisualMedia) permite que os usuários selecionem uma foto ou vídeo sem conceder acesso a toda a galeria. O aplicativo recebe apenas o URI dos arquivos selecionados. O PhotoPicker funciona sem declarar nenhuma permissão no manifesto.

private val pickMedia =
    registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
    if (uri != null) {
        // URI do arquivo selecionado, sem acesso a toda a biblioteca
        showImage(uri)
    }
}

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

PHPicker no iOS

No iOS 14+ foi introduzido o PHPickerViewController — um seletor do sistema que também não requer acesso a toda a biblioteca. O PHPicker é executado em um processo separado e não tem acesso à biblioteca do aplicativo. Esta é a maneira preferida de selecionar fotos para a maioria dos cenários.

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

Quando a Permissão Total é Necessária

O PhotoPicker não é adequado se o aplicativo precisar de acesso a toda a biblioteca para operações em massa: backup, sincronização em nuvem, aplicativo de galeria, gerenciador de arquivos. Nestes casos, é necessário solicitar Photo Library Permission e lidar com o caso de acesso limitado (Limited). Para iOS, é obrigatório incluir o tratamento do status .limited e oferecer aos usuários a opção de estender o acesso.

Melhores Práticas de Acesso à Galeria

As melhores práticas para trabalhar com Photo Library Permission ajudam a reduzir o número de negações e cumprir os requisitos de privacidade das plataformas.

Use PhotoPicker por Padrão

Para selecionar uma ou várias fotos, use o PhotoPicker ou PHPicker do sistema. Esses componentes não requerem permissões e proporcionam a melhor experiência do usuário. Solicite acesso total à galeria apenas se a funcionalidade do aplicativo exigir acesso a toda a biblioteca de mídia. Google e Apple recomendam explicitamente esta abordagem em sua documentação para desenvolvedores.

Explique o Motivo do Acesso Total

Se o aplicativo realmente precisar de acesso total à galeria, mostre uma tela preliminar com uma explicação. Explique por que todas as fotos são necessárias e não apenas uma. Por exemplo, um aplicativo de backup deve explicar que irá escanear todos os arquivos de mídia para criar uma cópia. A tela de pré-permissão é especialmente importante para iOS devido ao mecanismo de Acesso Limitado.

Solicite Apenas as Permissões Necessárias

Se o aplicativo apenas salva fotos mas não as lê (por exemplo, um editor de fotos que salva o resultado), solicite apenas a permissão de escrita na galeria. No Android, isso é WRITE_EXTERNAL_STORAGE (para Android 12 e versões anteriores) ou a API MediaStore sem permissões (para Android 10+). No iOS, use NSPhotoLibraryAddUsageDescription sem NSPhotoLibraryUsageDescription.