Info.plist Usage Description — qu'est-ce que c'est, clés NS*UsageDescription et configuration

Qu'est-ce que Info.plist Usage Description ?

Info.plist Usage Description sont des valeurs de chaîne des clés avec le préfixe NS*UsageDescription qui définissent le texte de la boîte de dialogue système lors de la demande d'accès aux ressources protégées d'iOS. Lorsqu'une application appelle pour la première fois une API nécessitant l'autorisation de l'utilisateur (par exemple, AVCaptureDevice pour la caméra), iOS affiche une boîte de dialogue avec ce texte et des boutons Autoriser/Refuser.

Le texte de description est la seule chose que le développeur peut contrôler dans la boîte de dialogue système. Le titre de la boîte de dialogue « souhaite accéder à [ressource] » est généré automatiquement par iOS en fonction du type de ressource demandée. Le développeur ne peut pas modifier le titre, les boutons ou l'apparence — seulement le texte explicatif.

Usage Description est étroitement lié au modèle des autorisations à l'exécution dans iOS. L'utilisateur accorde l'autorisation pour une demande, qui peut être révoquée ultérieurement via les Réglages. Lors d'une demande ultérieure, la boîte de dialogue ne s'affiche plus — l'application doit vérifier l'état de l'autorisation et répondre en conséquence.

Apple recommande vivement de spécifier une raison concrète pour la demande d'accès dans la description. Par exemple, « Pour prendre des photos de profil » est mieux que « Pour accéder à l'appareil photo ». Les textes spécifiques augmentent la confiance de l'utilisateur et le taux d'octroi. Selon Localytics (2023), les descriptions personnalisées augmentent le consentement de 15 à 25 % par rapport aux formulations génériques.

Différence entre Usage Description et ATT

Ne confondez pas NS*UsageDescription avec ATT (App Tracking Transparency). Usage Description est une demande d'accès aux ressources système (appareil photo, géolocalisation, photos), tandis qu'ATT est une demande de suivi (accès à l'IDFA). ATT utilise un framework séparé AppTrackingTransparency et la clé NSUserTrackingUsageDescription, qui ne fait pas partie de NS*UsageDescription.

Ce qu'ils ont en commun est que les deux utilisent une boîte de dialogue système avec un texte que l'application ne peut pas modifier. La différence est que Usage Description fonctionne au niveau des ressources, tandis qu'ATT fonctionne au niveau de l'identifiant de l'appareil. Les clés NS*UsageDescription ont été introduites dans iOS 6, ATT — dans iOS 14.5.

Évolution des clés dans différentes versions d'iOS

À chaque version d'iOS, Apple a ajouté de nouvelles ressources protégées et des clés correspondantes. iOS 6 : contacts, calendrier, rappels, photos. iOS 7 : microphone. iOS 8 : HomeKit, Santé. iOS 10 : bibliothèque multimédia, Siri. iOS 11 : NFC. iOS 14 : suivi (ATT). iOS 17 : accès au presse-papiers (nécessite une confirmation supplémentaire).

Important : si l'application utilise une API introduite dans une version spécifique d'iOS mais que la version minimale prise en charge est inférieure, la clé est toujours obligatoire. iOS vérifie la présence de la clé avant le premier appel API, quelle que soit la version sur laquelle l'application s'exécute.

Clés NS*UsageDescription obligatoires

La liste complète des clés dépend des fonctionnalités utilisées par l'application. Passons en revue les 14 clés principales les plus souvent requises dans les applications mobiles.

Accès multimédia

La clé NSCameraUsageDescription est obligatoire lors de l'accès à l'appareil photo via AVCaptureDevice ou UIImagePickerController avec la source .camera. La clé NSMicrophoneUsageDescription est nécessaire lors de l'enregistrement audio via AVAudioRecorder ou lors de la prise de vidéo avec son. Les deux clés sont souvent nécessaires ensemble si l'application enregistre une vidéo.

La clé NSPhotoLibraryUsageDescription est utilisée lors de la lecture de photos et vidéos depuis la bibliothèque multimédia de l'utilisateur via PHPicker ou UIImagePickerController. La clé NSPhotoLibraryAddUsageDescription est utilisée si l'application ne fait que sauvegarder des photos sans les lire. La première demande un accès en lecture, la seconde — un accès en écriture seule.

Géolocalisation et navigation

La clé NSLocationWhenInUseUsageDescription fournit l'accès à la géolocalisation lorsque l'application est active (à l'écran). NSLocationAlwaysAndWhenInUseUsageDescription fournit un accès permanent (y compris en mode arrière-plan). iOS nécessite les deux clés si un accès permanent est requis : d'abord WhenInUse, puis Always.

Les clés NSLocationTemporaryUsageDescription et NSLocationPreciseUsageDescription sont des clés supplémentaires pour demander un accès temporaire ou une géolocalisation précise. La localisation précise nécessite une autorisation séparée, et l'utilisateur peut activer uniquement la localisation approximative.

Contacts, calendrier et autres données

La clé NSContactsUsageDescription fournit l'accès aux contacts de l'utilisateur via CNContactStore. NSCalendarsUsageDescription fournit l'accès au calendrier pour lire et créer des événements. NSRemindersUsageDescription fournit l'accès aux rappels. NSBluetoothAlwaysUsageDescription fournit l'accès Bluetooth en arrière-plan (par exemple, pour les appareils BLE).

La clé NSHealthShareUsageDescription fournit l'accès en lecture aux données HealthKit. NSHealthUpdateUsageDescription fournit l'accès en écriture aux données HealthKit. Les deux sont obligatoires si l'application travaille avec des données de santé. Apple examine attentivement les applications utilisant HealthKit et peut rejeter l'application si la description d'utilisation ne correspond pas à la fonctionnalité.

Comment formuler correctement la description

Le texte dans Usage Description doit être spécifique, véridique et concis. Apple fournit des recommandations sur la formulation, et les examinateurs vérifient la conformité avec la fonctionnalité.

Structure d'une bonne description

Une bonne description se compose de trois parties : ce que l'application fait exactement avec la ressource, pourquoi l'utilisateur en a besoin, et quel bénéfice l'utilisateur retire de l'octroi de l'accès. Exemple : « Pour prendre des photos de profil et les télécharger sur votre profil. » Évitez les phrases génériques : « Pour améliorer les performances de l'application » n'explique pas pourquoi l'appareil photo est nécessaire.

Apple interdit les descriptions trompeuses. Si le texte dit « Pour prendre des photos » mais que l'application enregistre également des vidéos, cela peut être considéré comme trompeur. L'examinateur peut rejeter l'application ou demander des éclaircissements. Dans iOS 17, Apple a ajouté une validation automatique : la description doit contenir des mots-clés correspondant à la ressource demandée.

Localisation : la description doit être traduite dans toutes les langues prises en charge par l'application. Si l'application est disponible en 10 langues, chaque clé Usage Description doit avoir des traductions dans les fichiers Localizable.strings ou InfoPlist.strings. Apple recommande d'utiliser InfoPlist.strings pour localiser les clés Info.plist.

Exemples mauvais et bons

• Mauvais : « Nécessite un accès à l'appareil photo » — n'explique pas pourquoi
• Bon : « Pour scanner les codes QR lors du paiement » — spécifique et clair
• Mauvais : « Pour déterminer la localisation » — vague
• Bon : « Pour trouver les restaurants à proximité sur la carte » — montre la valeur
• Mauvais : « Pour améliorer le service » — peu informatif
• Bon : « Pour télécharger des photos dans un avis produit » — action spécifique

Localisation via InfoPlist.strings

Pour localiser Usage Description, il n'est pas nécessaire de dupliquer Info.plist pour chaque langue. Créez un fichier InfoPlist.strings dans chaque répertoire de langue et spécifiez les valeurs des clés. iOS utilisera automatiquement la bonne langue dans la boîte de dialogue. Xcode prend en charge la localisation de base pour Info.plist à partir de la version 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Pour scanner les codes QR";
"NSPhotoLibraryUsageDescription" =
    "Pour télécharger des images sur le profil";
"NSLocationWhenInUseUsageDescription" =
    "Pour afficher les magasins à proximité sur la carte";

Implémentation : code et paramètres

L'implémentation correcte de Usage Description comprend l'ajout de clés à Info.plist, la vérification de l'état d'autorisation dans le code et la gestion du refus.

Ajout de clés via Xcode

Dans Xcode, ouvrez Info.plist, survolez une ligne et cliquez sur « + ». Saisissez le nom de la clé (par exemple, NSCameraUsageDescription) et spécifiez la chaîne de description. Xcode complète automatiquement les noms des clés, réduisant le risque de fautes de frappe. Après l'ajout, recompilez le projet et vérifiez que la clé apparaît dans le binaire final.

Important : les clés sont sensibles à la casse. NSCameraUsageDescription est correct, NSCamerausagedescription est une erreur. Une clé incorrecte est ignorée et l'application plantera lors de l'appel à l'API. Utilisez la copie depuis la documentation Apple ou l'autocomplétion de Xcode pour éviter les fautes de frappe.

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

Gestion du refus d'accès

Si l'utilisateur refuse l'accès, l'application ne doit pas rappeler la boîte de dialogue système — ce n'est pas possible. Affichez plutôt un écran d'information expliquant comment activer l'accès via les Réglages, avec un bouton « Ouvrir les réglages » (UIApplicationOpenSettingsURLString). Cette pratique améliore l'expérience utilisateur et la probabilité que l'utilisateur active l'accès.

N'affichez pas une alerte demandant d'activer l'accès immédiatement après le refus — donnez à l'utilisateur le temps de comprendre pourquoi il pourrait avoir besoin de cette fonctionnalité. Il est préférable d'afficher l'explication lors de la tentative d'utilisation de la fonctionnalité qui nécessite cette autorisation. UX Movement (2023) recommande d'afficher l'écran d'explication 2 à 3 sessions après le refus.

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

Que se passe-t-il si vous ne spécifiez pas Usage Description

L'absence d'une clé Usage Description obligatoire provoque un plantage immédiat de l'application au premier appel de l'API correspondante. Ce n'est pas un avertissement Xcode, mais un plantage à l'exécution avec NSInvalidArgumentException et un message dans la console : « Cette application a planté car elle a tenté d'accéder à des données sensibles à la vie privée sans description d'utilisation. »

Comportement à l'exécution sans la clé

iOS vérifie la présence de la clé NS*UsageDescription dans Info.plist au premier appel API pour une ressource protégée. Si la clé est absente, le système d'exploitation termine immédiatement l'application avec un signal SIGABRT. Cela se produit même sur les appareils de débogage — Xcode affiche l'exception dans le journal, mais le débogueur ne la capture pas comme point d'arrêt.

Le plantage se reproduit sur les appareils réels et le simulateur. La seule façon de l'éviter est d'ajouter la clé avant d'appeler l'API. L'analyseur statique de Xcode n'avertit pas toujours de l'absence de clé, surtout si l'API est appelée via des SDK tiers. Les testeurs TestFlight verront également le plantage, ce qui peut entraîner des avis négatifs.

Situation particulière avec iOS 17+ : Apple a introduit une vérification supplémentaire pour l'accès au presse-papiers (UIPasteboard). Si l'application lit le presse-papiers sans action explicite de l'utilisateur, iOS affiche une bannière d'avertissement, même si la clé Usage Description est présente. Le presse-papiers ne nécessite pas de clé séparée, mais Apple recommande de minimiser la lecture automatique.

Erreurs lors de la révision App Store

Outre le plantage à l'exécution, l'absence de clé peut entraîner le rejet de l'application lors de la révision. Apple vérifie Info.plist à l'étape de la révision et peut rejeter la compilation si elle détecte des appels API sans clés correspondantes. Xcode ne bloque pas l'archivage, mais App Store Connect peut retourner une erreur lors du traitement du binaire.

Si l'application n'utilise pas la ressource directement mais qu'un SDK tiers le fait (par exemple, un SDK d'analyse demande l'IDFA), le développeur doit quand même ajouter la clé correspondante. Apple vérifie tous les appels API dans le binaire, y compris le code des bibliothèques statiques et dynamiques. L'erreur « Clé Info.plist manquante » est l'une des raisons les plus courantes de rejet des mises à jour.