Info.plist Usage Description — o que é, chaves NS*UsageDescription e configuração

O que é Info.plist Usage Description?

Info.plist Usage Description são valores de string das chaves com o prefixo NS*UsageDescription que definem o texto do diálogo do sistema ao solicitar acesso a recursos protegidos do iOS. Quando um aplicativo chama pela primeira vez uma API que requer permissão do usuário (por exemplo, AVCaptureDevice para a câmera), o iOS exibe um diálogo com este texto e botões de permitir ou negar.

O texto da descrição é a única coisa que o desenvolvedor pode controlar no diálogo do sistema. O título do diálogo “ quer acessar [recurso]” é gerado automaticamente pelo iOS com base no tipo de recurso solicitado. O desenvolvedor não pode alterar o título, botões ou aparência — apenas o texto explicativo.

Usage Description está intimamente ligado ao modelo de permissões em tempo de execução no iOS. O usuário concede permissão para uma solicitação, que pode ser revogada posteriormente através de Ajustes. Em uma solicitação subsequente, o diálogo não é exibido novamente — o aplicativo deve verificar o status da permissão e responder adequadamente.

A Apple recomenda fortemente especificar um motivo concreto para a solicitação de acesso na descrição. Por exemplo, “Para tirar fotos de perfil” é melhor que “Para acessar a câmera”. Textos específicos aumentam a confiança do usuário e a taxa de concessão. De acordo com a Localytics (2023), descrições personalizadas aumentam o consentimento em 15-25% em comparação com formulações genéricas.

Diferença entre Usage Description e ATT

Não confunda NS*UsageDescription com ATT (App Tracking Transparency). Usage Description é uma solicitação de acesso a recursos do sistema (câmera, geolocalização, fotos), enquanto ATT é uma solicitação de rastreamento (acesso ao IDFA). O ATT usa um framework separado AppTrackingTransparency e a chave NSUserTrackingUsageDescription, que não faz parte do NS*UsageDescription.

O que eles têm em comum é que ambos usam um diálogo do sistema com texto que o aplicativo não pode modificar. A diferença é que o Usage Description opera no nível de recursos, enquanto o ATT opera no nível do identificador do dispositivo. As chaves NS*UsageDescription foram introduzidas no iOS 6, ATT — no iOS 14.5.

Evolução das chaves em diferentes versões do iOS

A cada lançamento do iOS, a Apple adicionou novos recursos protegidos e chaves correspondentes. iOS 6: contatos, calendário, lembretes, fotos. iOS 7: microfone. iOS 8: HomeKit, Saúde. iOS 10: biblioteca de mídia, Siri. iOS 11: NFC. iOS 14: rastreamento (ATT). iOS 17: acesso à área de transferência (requer confirmação adicional).

Importante: se o aplicativo usa uma API introduzida em uma versão específica do iOS, mas a versão mínima suportada é inferior, a chave continua obrigatória. O iOS verifica a presença da chave antes da primeira chamada à API, independentemente da versão em que o aplicativo está sendo executado.

Chaves NS*UsageDescription obrigatórias

A lista completa de chaves depende de quais recursos o aplicativo utiliza. Vamos revisar as 14 principais chaves mais comumente exigidas em aplicativos móveis.

Acesso a mídia

A chave NSCameraUsageDescription é obrigatória ao acessar a câmera através de AVCaptureDevice ou UIImagePickerController com fonte .camera. A chave NSMicrophoneUsageDescription é necessária ao gravar áudio através de AVAudioRecorder ou ao gravar vídeo com som. Ambas as chaves são frequentemente necessárias juntas se o aplicativo grava vídeo.

A chave NSPhotoLibraryUsageDescription é usada ao ler fotos e vídeos da biblioteca de mídia do usuário através de PHPicker ou UIImagePickerController. A chave NSPhotoLibraryAddUsageDescription é usada se o aplicativo apenas salva fotos, mas não as lê. A primeira solicita acesso de leitura, a segunda — apenas de escrita.

Geolocalização e navegação

A chave NSLocationWhenInUseUsageDescription fornece acesso à geolocalização quando o aplicativo está ativo (na tela). NSLocationAlwaysAndWhenInUseUsageDescription fornece acesso sempre (incluindo modo em segundo plano). O iOS requer ambas as chaves se for necessário acesso permanente: primeiro WhenInUse, depois Always.

As chaves NSLocationTemporaryUsageDescription e NSLocationPreciseUsageDescription são chaves adicionais para solicitar acesso temporário ou geolocalização precisa. A localização precisa requer permissão separada, e o usuário pode ativar apenas a localização aproximada.

Contatos, calendário e outros dados

A chave NSContactsUsageDescription fornece acesso aos contatos do usuário através do CNContactStore. NSCalendarsUsageDescription fornece acesso ao calendário para ler e criar eventos. NSRemindersUsageDescription fornece acesso a lembretes. NSBluetoothAlwaysUsageDescription fornece acesso ao Bluetooth em segundo plano (por exemplo, para dispositivos BLE).

A chave NSHealthShareUsageDescription fornece acesso para ler dados do HealthKit. NSHealthUpdateUsageDescription fornece acesso para escrever dados no HealthKit. Ambas são obrigatórias se o aplicativo trabalha com dados de saúde. A Apple revisa cuidadosamente os aplicativos que usam HealthKit e pode rejeitar o aplicativo se a descrição de uso não corresponder à funcionalidade.

Como redigir a descrição corretamente

O texto em Usage Description deve ser específico, verdadeiro e conciso. A Apple fornece recomendações sobre a redação, e os revisores verificam a correspondência com a funcionalidade.

Estrutura de uma boa descrição

Uma boa descrição consiste em três partes: o que exatamente o aplicativo faz com o recurso, por que o usuário precisa disso e qual benefício o usuário obtém ao conceder acesso. Exemplo: “Para tirar fotos de perfil e enviá-las ao seu perfil.” Evite frases genéricas: “Para melhorar o desempenho do aplicativo” não explica por que a câmera é necessária.

A Apple proíbe descrições enganosas. Se diz “Para tirar fotos”, mas o aplicativo também grava vídeo, isso pode ser considerado enganoso. O revisor pode rejeitar o aplicativo ou solicitar esclarecimentos. No iOS 17, a Apple adicionou validação automática: a descrição deve conter palavras-chave correspondentes ao recurso solicitado.

Localização: a descrição deve ser traduzida para todos os idiomas suportados pelo aplicativo. Se o aplicativo estiver disponível em 10 idiomas, cada chave Usage Description deve ter traduções nos arquivos Localizable.strings ou InfoPlist.strings. A Apple recomenda usar InfoPlist.strings para localizar as chaves do Info.plist.

Exemplos ruins e bons

• Ruim: “Precisa de acesso à câmera” — não explica por quê
• Bom: “Para escanear códigos QR ao pagar” — específico e claro
• Ruim: “Para determinar localização” — vago
• Bom: “Para encontrar restaurantes próximos no mapa” — mostra valor
• Ruim: “Para melhorar o serviço” — pouco informativo
• Bom: “Para enviar fotos para uma avaliação de produto” — ação específica

Localização via InfoPlist.strings

Para localizar Usage Description, não é necessário duplicar o Info.plist para cada idioma. Crie um arquivo InfoPlist.strings em cada diretório de idioma e especifique os valores das chaves. O iOS substituirá automaticamente o idioma correto no diálogo. O Xcode suporta localização base para Info.plist a partir da versão 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Para escanear códigos QR";
"NSPhotoLibraryUsageDescription" =
    "Para enviar imagens para o perfil";
"NSLocationWhenInUseUsageDescription" =
    "Para exibir lojas próximas no mapa";

Implementação: código e configurações

A implementação correta do Usage Description inclui adicionar chaves ao Info.plist, verificar o status da permissão no código e lidar com a negação.

Adicionando chaves via Xcode

No Xcode, abra o Info.plist, passe o mouse sobre uma linha e clique em “+”. Digite o nome da chave (por exemplo, NSCameraUsageDescription) e especifique a string de descrição. O Xcode preenche automaticamente os nomes das chaves, reduzindo o risco de erros de digitação. Após adicionar, recompile o projeto e verifique se a chave aparece no binário final.

Importante: as chaves diferenciam maiúsculas de minúsculas. NSCameraUsageDescription está correto, NSCamerausagedescription é um erro. Uma chave incorreta é ignorada e o aplicativo falhará ao chamar a API. Use cópia da documentação da Apple ou o preenchimento automático do Xcode para evitar erros de digitação.

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

Lidando com a negação de acesso

Se o usuário negar o acesso, o aplicativo não deve chamar o diálogo do sistema novamente — não é possível. Em vez disso, mostre uma tela informativa explicando como ativar o acesso através de Ajustes, com um botão “Abrir Ajustes” (UIApplicationOpenSettingsURLString). Esta prática melhora a experiência do usuário e a probabilidade de o usuário ativar o acesso.

Não mostre um alerta pedindo para ativar o acesso imediatamente após a negação — dê tempo ao usuário para entender por que ele pode precisar deste recurso. É melhor mostrar a explicação ao tentar usar a funcionalidade que requer esta permissão. O UX Movement (2023) recomenda mostrar a tela de explicação 2-3 sessões após a negação.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Acesso a \(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)
}

O que acontece se não especificar Usage Description

A ausência de uma chave Usage Description obrigatória causa uma falha imediata do aplicativo na primeira chamada à API correspondente. Isso não é um aviso do Xcode, mas uma falha em tempo de execução com NSInvalidArgumentException e uma mensagem no console: “Este aplicativo falhou porque tentou acessar dados sensíveis de privacidade sem uma descrição de uso.”

Comportamento em tempo de execução sem a chave

O iOS verifica a presença da chave NS*UsageDescription no Info.plist na primeira chamada à API para um recurso protegido. Se a chave estiver ausente, o sistema operacional encerra imediatamente o aplicativo com um sinal SIGABRT. Isso acontece mesmo em dispositivos de depuração — o Xcode mostra a exceção no log, mas o depurador não a captura como ponto de interrupção.

A falha se reproduz em dispositivos reais e no simulador. A única maneira de evitar é adicionar a chave antes de chamar a API. O analisador estático do Xcode nem sempre avisa sobre chaves ausentes, especialmente se a API for chamada através de SDKs de terceiros. Os testadores do TestFlight também verão a falha, o que pode levar a avaliações negativas.

Situação especial com iOS 17+: a Apple introduziu uma verificação adicional para acesso à área de transferência (UIPasteboard). Se o aplicativo ler a área de transferência sem uma ação explícita do usuário, o iOS mostra um banner de aviso, mesmo que a chave Usage Description esteja presente. A área de transferência não requer uma chave separada, mas a Apple recomenda minimizar a leitura automática.

Erros na revisão da App Store

Além da falha em tempo de execução, a ausência de uma chave pode causar a rejeição do aplicativo durante a revisão. A Apple verifica o Info.plist na fase de revisão e pode rejeitar a compilação se detectar chamadas à API sem as chaves correspondentes. O Xcode não bloqueia o arquivamento, mas o App Store Connect pode retornar um erro ao processar o binário.

Se o aplicativo não usar o recurso diretamente, mas um SDK de terceiros o fizer (por exemplo, um SDK de análise solicita IDFA), o desenvolvedor ainda deve adicionar a chave correspondente. A Apple verifica todas as chamadas à API no binário, incluindo código de bibliotecas estáticas e dinâmicas. O erro “Chave Info.plist ausente” é uma das causas mais comuns de rejeição de atualizações.