Info.plist Usage Description — qué es, claves NS*UsageDescription y configuración

¿Qué es Info.plist Usage Description?

Info.plist Usage Description son valores de cadena de las claves con el prefijo NS*UsageDescription que definen el texto del diálogo del sistema al solicitar acceso a recursos protegidos de iOS. Cuando una aplicación llama por primera vez a una API que requiere permiso del usuario (por ejemplo, AVCaptureDevice para la cámara), iOS muestra un diálogo con este texto y botones de permitir o denegar.

El texto de la descripción es lo único que el desarrollador puede controlar en el diálogo del sistema. El título del diálogo “ quiere acceder a [recurso]” lo genera iOS automáticamente según el tipo de recurso solicitado. El desarrollador no puede cambiar el título, los botones ni la apariencia, solo el texto explicativo.

Usage Description está estrechamente relacionado con el modelo de permisos en tiempo de ejecución en iOS. El usuario concede permiso para una solicitud, que puede revocarse más tarde a través de Ajustes. En una solicitud posterior, el diálogo no se vuelve a mostrar: la aplicación debe comprobar el estado del permiso y responder en consecuencia.

Apple recomienda encarecidamente especificar un motivo concreto para la solicitud de acceso en la descripción. Por ejemplo, “Para tomar fotos de perfil” es mejor que “Para acceder a la cámara”. Los textos específicos aumentan la confianza del usuario y la tasa de concesión. Según Localytics (2023), las descripciones personalizadas aumentan el consentimiento entre un 15 y un 25% en comparación con las formulaciones genéricas.

Diferencia entre Usage Description y ATT

No confundas NS*UsageDescription con ATT (App Tracking Transparency). Usage Description es una solicitud de acceso a recursos del sistema (cámara, geolocalización, fotos), mientras que ATT es una solicitud de seguimiento (acceso a IDFA). ATT utiliza un framework separado AppTrackingTransparency y la clave NSUserTrackingUsageDescription, que no forma parte de NS*UsageDescription.

Lo que tienen en común es que ambos usan un diálogo del sistema con texto que la aplicación no puede modificar. La diferencia es que Usage Description opera a nivel de recursos, mientras que ATT opera a nivel del identificador del dispositivo. Las claves NS*UsageDescription se introdujeron en iOS 6, ATT en iOS 14.5.

Evolución de las claves en distintas versiones de iOS

Con cada lanzamiento de iOS, Apple añadió nuevos recursos protegidos y claves correspondientes. iOS 6: contactos, calendario, recordatorios, fotos. iOS 7: micrófono. iOS 8: HomeKit, Salud. iOS 10: biblioteca multimedia, Siri. iOS 11: NFC. iOS 14: seguimiento (ATT). iOS 17: acceso al portapapeles (requiere confirmación adicional).

Importante: si la aplicación usa una API introducida en una versión específica de iOS pero la versión mínima compatible es inferior, la clave sigue siendo obligatoria. iOS comprueba la presencia de la clave antes de la primera llamada a la API, independientemente de la versión en la que se ejecute la aplicación.

Claves NS*UsageDescription obligatorias

La lista completa de claves depende de las funciones que utilice la aplicación. Revisemos las 14 claves principales que se requieren con más frecuencia en aplicaciones móviles.

Acceso a multimedia

La clave NSCameraUsageDescription es obligatoria al acceder a la cámara a través de AVCaptureDevice o UIImagePickerController con fuente .camera. La clave NSMicrophoneUsageDescription es necesaria al grabar audio mediante AVAudioRecorder o al grabar vídeo con sonido. Ambas claves suelen ser necesarias juntas si la aplicación graba vídeo.

La clave NSPhotoLibraryUsageDescription se utiliza al leer fotos y vídeos de la biblioteca multimedia del usuario a través de PHPicker o UIImagePickerController. La clave NSPhotoLibraryAddUsageDescription se utiliza si la aplicación solo guarda fotos pero no las lee. La primera solicita acceso de lectura, la segunda solo de escritura.

Geolocalización y navegación

La clave NSLocationWhenInUseUsageDescription proporciona acceso a la geolocalización cuando la aplicación está activa (en pantalla). NSLocationAlwaysAndWhenInUseUsageDescription proporciona acceso siempre (incluyendo el modo en segundo plano). iOS requiere ambas claves si se necesita acceso permanente: primero WhenInUse, luego Always.

Las claves NSLocationTemporaryUsageDescription y NSLocationPreciseUsageDescription son claves adicionales para solicitar acceso temporal o geolocalización precisa. La ubicación precisa requiere un permiso separado, y el usuario puede activar solo la ubicación aproximada.

Contactos, calendario y otros datos

La clave NSContactsUsageDescription proporciona acceso a los contactos del usuario a través de CNContactStore. NSCalendarsUsageDescription proporciona acceso al calendario para leer y crear eventos. NSRemindersUsageDescription proporciona acceso a los recordatorios. NSBluetoothAlwaysUsageDescription proporciona acceso a Bluetooth en segundo plano (por ejemplo, para dispositivos BLE).

La clave NSHealthShareUsageDescription proporciona acceso para leer datos de HealthKit. NSHealthUpdateUsageDescription proporciona acceso para escribir datos en HealthKit. Ambas son obligatorias si la aplicación trabaja con datos de salud. Apple revisa cuidadosamente las aplicaciones que usan HealthKit y puede rechazar la aplicación si la descripción de uso no coincide con la funcionalidad.

Cómo redactar la descripción correctamente

El texto en Usage Description debe ser específico, veraz y conciso. Apple ofrece recomendaciones sobre la redacción y los revisores verifican que coincida con la funcionalidad.

Estructura de una buena descripción

Una buena descripción consta de tres partes: qué hace exactamente la aplicación con el recurso, por qué lo necesita el usuario y qué beneficio obtiene el usuario al conceder el acceso. Ejemplo: “Para tomar fotos de perfil y subirlas a tu perfil”. Evita frases genéricas: “Para mejorar el rendimiento de la aplicación” no explica por qué se necesita la cámara.

Apple prohíbe descripciones engañosas. Si dice “Para tomar fotos” pero la aplicación también graba vídeo, puede considerarse engañoso. El revisor puede rechazar la aplicación o solicitar aclaraciones. En iOS 17, Apple añadió validación automática: la descripción debe contener palabras clave correspondientes al recurso solicitado.

Localización: la descripción debe traducirse a todos los idiomas que soporte la aplicación. Si la aplicación está disponible en 10 idiomas, cada clave Usage Description debe tener traducciones en archivos Localizable.strings o InfoPlist.strings. Apple recomienda usar InfoPlist.strings para localizar las claves de Info.plist.

Ejemplos buenos y malos

• Malo: “Necesita acceso a la cámara” — no explica por qué
• Bueno: “Para escanear códigos QR al pagar” — específico y claro
• Malo: “Para determinar la ubicación” — vago
• Bueno: “Para buscar restaurantes cercanos en el mapa” — muestra el valor
• Malo: “Para mejorar el servicio” — poco informativo
• Bueno: “Para subir fotos a una reseña de producto” — acción específica

Localización mediante InfoPlist.strings

Para localizar Usage Description no es necesario duplicar Info.plist para cada idioma. Crea un archivo InfoPlist.strings en cada directorio de idioma e indica los valores de las claves. iOS sustituirá automáticamente el idioma correcto en el diálogo. Xcode admite localización base para Info.plist a partir de la versión 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Para escanear códigos QR";
"NSPhotoLibraryUsageDescription" =
    "Para cargar imágenes al perfil";
"NSLocationWhenInUseUsageDescription" =
    "Para mostrar tiendas cercanas en el mapa";

Implementación: código y configuración

La implementación correcta de Usage Description incluye añadir claves a Info.plist, comprobar el estado del permiso en el código y gestionar la denegación.

Añadir claves mediante Xcode

En Xcode, abre Info.plist, coloca el cursor sobre una fila y haz clic en “+”. Introduce el nombre de la clave (por ejemplo, NSCameraUsageDescription) y especifica la cadena de descripción. Xcode autocompleta los nombres de las claves, lo que reduce el riesgo de errores tipográficos. Después de añadirlas, recompila el proyecto y verifica que la clave aparezca en el binario final.

Importante: las claves distinguen mayúsculas y minúsculas. NSCameraUsageDescription es correcto, NSCamerausagedescription es un error. Una clave incorrecta se ignora y la aplicación fallará al llamar a la API. Usa la copia de la documentación de Apple o el autocompletado de Xcode para evitar errores tipográficos.

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

Gestión de la denegación de acceso

Si el usuario deniega el acceso, la aplicación no debe volver a mostrar el diálogo del sistema, no es posible. En su lugar, muestra una pantalla informativa que explique cómo activar el acceso a través de Ajustes, con un botón “Abrir Ajustes” (UIApplicationOpenSettingsURLString). Esta práctica mejora la experiencia de usuario y la probabilidad de que el usuario active el acceso.

No muestres una alerta pidiendo activar el acceso inmediatamente después de la denegación: dale tiempo al usuario para entender por qué podría necesitar esta función. Es mejor mostrar la explicación al intentar usar la funcionalidad que requiere este permiso. UX Movement (2023) recomienda mostrar la pantalla de explicación 2 o 3 sesiones después de la denegación.

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

Qué ocurre si no se especifica Usage Description

La ausencia de una clave Usage Description obligatoria provoca un bloqueo inmediato de la aplicación en la primera llamada a la API correspondiente. No es una advertencia de Xcode, sino un bloqueo en tiempo de ejecución con NSInvalidArgumentException y un mensaje en la consola: “Esta aplicación ha fallado porque intentó acceder a datos sensibles de privacidad sin una descripción de uso”.

Comportamiento en tiempo de ejecución sin la clave

iOS comprueba la presencia de la clave NS*UsageDescription en Info.plist en la primera llamada a la API para un recurso protegido. Si la clave falta, el sistema operativo termina inmediatamente la aplicación con una señal SIGABRT. Esto ocurre incluso en dispositivos de depuración: Xcode muestra la excepción en el registro, pero el depurador no la captura como punto de interrupción.

El bloqueo se reproduce en dispositivos reales y en el simulador. La única forma de evitarlo es añadir la clave antes de llamar a la API. El analizador estático de Xcode no siempre advierte sobre la falta de claves, especialmente si la API se llama a través de SDK de terceros. Los evaluadores de TestFlight también verán el bloqueo, lo que puede generar reseñas negativas.

Situación especial con iOS 17+: Apple introdujo una verificación adicional para el acceso al portapapeles (UIPasteboard). Si la aplicación lee el portapapeles sin una acción explícita del usuario, iOS muestra un banner de advertencia, incluso si la clave Usage Description está presente. El portapapeles no requiere una clave separada, pero Apple recomienda minimizar la lectura automática.

Errores en la revisión de App Store

Además del bloqueo en tiempo de ejecución, la ausencia de una clave puede provocar el rechazo de la aplicación durante la revisión. Apple comprueba Info.plist en la etapa de revisión y puede rechazar la compilación si detecta llamadas a la API sin las claves correspondientes. Xcode no bloquea el archivado, pero App Store Connect puede devolver un error al procesar el binario.

Si la aplicación no usa el recurso directamente pero un SDK de terceros lo hace (por ejemplo, un SDK de análisis solicita IDFA), el desarrollador igualmente debe añadir la clave correspondiente. Apple comprueba todas las llamadas a la API en el binario, incluyendo el código de bibliotecas estáticas y dinámicas. El error “Falta la clave Info.plist” es una de las causas más comunes de rechazo de actualizaciones.