Paramétrer les configurations gérées

Si vous développez des applications pour le marché des entreprises, vous devrez peut-être pour répondre à des exigences particulières définies par les règles d'une organisation. Les configurations gérées, auparavant appelées restrictions d'application, autoriser l'administrateur informatique de l'organisation à spécifier à distance les paramètres applications. Cette fonctionnalité est particulièrement utile pour les les applications déployées sur un profil professionnel.

Par exemple, une organisation peut exiger que les applications approuvées autorisent Administrateur informatique à:

• Autoriser ou bloquer des URL dans un navigateur Web
• Indiquer si une application est autorisée à synchroniser le contenu via les réseaux mobiles, ou simplement par Wi-Fi
• Configurer les paramètres de messagerie de l'application

Ce guide explique comment implémenter des paramètres de configuration gérée dans votre application. Pour afficher des exemples d'applications avec une configuration gérée, consultez la page ManagedConfigurations. Si vous êtes un développeur de gestion de la mobilité en entreprise (EMM), consultez le guide de l'API Android Management.

Remarque:Pour des raisons d'historique, ces paramètres de configuration sont appelés restrictions,et sont implémentées avec les fichiers et les classes qui l'utilisent. (par exemple, RestrictionsManager). Toutefois, ces des restrictions peuvent en fait mettre en œuvre un large éventail d'options de configuration, pas seulement des restrictions sur le fonctionnement de l’application.

Présentation de la configuration à distance

Les applications définissent les options de configuration gérées qui peuvent être défini par un administrateur informatique. Il s'agit de paramètres arbitraires qui peuvent être par un fournisseur de configuration gérée. Si votre application s'exécute dans un profil professionnel, l'administrateur informatique peut modifier la configuration gérée de votre application.

Le fournisseur de configurations gérées est une autre application exécutée sur le même appareil. Cette application est généralement contrôlée par l'administrateur informatique. La L'administrateur informatique communique les modifications de configuration au de votre application de fournisseur de configuration. Cette application modifie à son tour les configurations de votre application.

Pour fournir des configurations gérées en externe, procédez comme suit:

• Déclarez les configurations gérées dans le fichier manifeste de votre application. Faire permet donc à l'administrateur informatique de lire via les API Google Play.
• Chaque fois que l'application reprend, utilisez l'objet RestrictionsManager pour vérifier l'état actuel des configurations gérées, et modifier l'UI et le comportement de votre application pour à ces configurations.
• Écoutez l'événement Intent ACTION_APPLICATION_RESTRICTIONS_CHANGED. Lorsque vous recevez ce sur votre annonce, consultez le RestrictionsManager pour voir les configurations gérées actuelles, et apportez les modifications nécessaires à vos le comportement de votre application.

Définir des configurations gérées

Votre application est compatible avec toutes les configurations gérées que vous souhaitez définir. Vous déclarez les configurations gérées de l'application dans un fichier de configurations gérées, puis déclarez le fichier de configuration dans le fichier manifeste. La création d'un fichier de configuration permet d'autres applications pour examiner les configurations gérées fournies par votre application. Partenaires EMM peut lire les configurations de votre application à l'aide des API Google Play.

Pour définir les options de configuration à distance de votre application, placez l'élément suivant dans le fichier manifeste de votre <ph type="x-smartling-placeholder"></ph> <application>:

<meta-data android:name="android.content.APP_RESTRICTIONS"
    android:resource="@xml/app_restrictions" />

Créez un fichier nommé app_restrictions.xml dans le fichier res/xml. La structure de ce fichier est décrite dans la référence de RestrictionsManager. Le fichier comporte un élément <restrictions> unique de premier niveau, qui contient Un élément enfant <restriction> pour chaque configuration de l'application.

Remarque:Ne créez pas de versions localisées des de configuration gérée. Votre application ne peut avoir qu'un fichier unique de configurations gérées. Les configurations seront donc cohérente pour votre application dans toutes les langues.

Dans un environnement d'entreprise, un EMM utilise généralement le service géré schéma de configuration permettant de générer une console distante afin qu'ils puissent configurer à distance application.

Le fournisseur de configuration gérée peut interroger l'application pour obtenir des détails sur les configurations disponibles pour l'application, y compris leur description texte. Le fournisseur de configuration et l'administrateur informatique peuvent modifier le paramètre des configurations gérées à tout moment, même lorsque l'application n'est pas en cours d'exécution.

Par exemple, supposons que votre application puisse être configurée à distance pour autoriser ou interdire pour télécharger des données via une connexion au réseau mobile. Votre application peut présenter <restriction>:

<?xml version="1.0" encoding="utf-8"?>
<restrictions xmlns:android="http://schemas.android.com/apk/res/android">

  <restriction
    android:key="downloadOnCellular"
    android:title="@string/download_on_cell_title"
    android:restrictionType="bool"
    android:description="@string/download_on_cell_description"
    android:defaultValue="true" />

</restrictions>

Vous devez utiliser l'attribut android:key de chaque configuration pour lire sa valeur à partir d'un bundle de configuration géré. Pour cette raison, chaque configuration doit avoir une chaîne de clé unique, et la chaîne ne peut pas être localisée. Il doit être spécifié avec un littéral de chaîne.

Remarque:Dans une application de production, android:title et android:description doit être extrait d'une ressource localisée , comme décrit à la section Localiser avec des ressources :

Une application définit des restrictions à l'aide de groupes dans un bundle_array. Par exemple, une application avec plusieurs options de connexion VPN pourrait définir chaque serveur VPN. configuration dans un bundle, avec plusieurs groupes regroupés dans un tableau de groupes:

<?xml version="1.0" encoding="utf-8"?>
<restrictions xmlns:android="http://schemas.android.com/apk/res/android" >

  <restriction
    android:key="vpn_configuration_list"
    android:restrictionType="bundle_array">
    <restriction
      android:key="vpn_configuration"
      android:restrictionType="bundle">
      <restriction
        android:key="vpn_server"
        android:restrictionType="string"/>
      <restriction
        android:key="vpn_username"
        android:restrictionType="string"/>
      <restriction
        android:key="vpn_password"
        android:restrictionType="string"/>
    </restriction>
  </restriction>

</restrictions>

Types acceptés pour l'élément android:restrictionType sont répertoriés dans le Tableau 1 et documentés dans la référence pour RestrictionsManager et RestrictionEntry

Tableau 1. Types d'entrées de restriction et utilisation.

Type	android:restrictionType	Utilisation habituelle
TYPE_BOOLEAN	"bool"	Valeur booléenne, "true" ou "false".
TYPE_STRING	"string"	Valeur de chaîne, telle qu'un nom.
TYPE_INTEGER	"integer"	Entier dont la valeur est comprise entre MIN_VALUE jusqu'à MAX_VALUE
TYPE_CHOICE	"choice"	Une valeur de chaîne sélectionnée parmi android:entryValues, généralement présenté sous la forme d'une liste à sélection unique.
TYPE_MULTI_SELECT	"multi-select"	Tableau de chaînes avec des valeurs sélectionnées dans android:entryValues. Utilisez cette option pour présenter une liste à sélection multiple dans laquelle plusieurs entrée pouvant être sélectionnée, par exemple pour choisir des titres spécifiques à ajouter à la liste d'autorisation.
TYPE_NULL	"hidden"	Type de restriction masqué. Utilisez ce type pour les informations doit être transféré, mais ne doit pas être présenté à l'utilisateur dans l'UI. Stocke une seule valeur de chaîne.
TYPE_BUNDLE_ARRAY	"bundle_array"	Utilisez-le pour stocker des tableaux de restriction bundles Disponible sous Android 6.0 (niveau d'API 23).

Remarque:Les android:entryValues sont lisibles par un ordinateur et ne peuvent pas être localisés. Utilisez android:entries pour présenter des valeurs lisibles par l'humain pouvant être localisées. Chaque entrée doit avoir un index correspondant dans android:entryValues.

Vérifier les configurations gérées

Votre application ne reçoit pas de notification automatique lorsque d'autres applications modifient sa paramètres de configuration. À la place, vous devez vérifier correspond au démarrage ou à la reprise de votre application, et écoutez l'intent du système pour savoir si les configurations changent l'application est en cours d'exécution.

Pour déterminer les paramètres de configuration actuels, votre application utilise un RestrictionsManager. Votre application doit recherchez les configurations gérées actuelles aux moments suivants:

• Lorsque l'application démarre ou reprend, dans son onResume() méthode
• Lorsque l'application est informée d'un changement de configuration, comme décrit dans Détecter les configurations gérées Modifications

Pour obtenir un objet RestrictionsManager, obtenez la valeur actuelle activité avec getActivity(), puis appelez la méthode Activity.getSystemService() de cette activité:

Kotlin

var myRestrictionsMgr =
        activity?.getSystemService(Context.RESTRICTIONS_SERVICE) as RestrictionsManager

Java

RestrictionsManager myRestrictionsMgr =
    (RestrictionsManager) getActivity()
        .getSystemService(Context.RESTRICTIONS_SERVICE);

Une fois que vous disposez d'un RestrictionsManager, vous pouvez obtenir paramètres de configuration actuels en appelant la méthode Méthode getApplicationRestrictions():

Kotlin

var appRestrictions: Bundle = myRestrictionsMgr.applicationRestrictions

Java

Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

Remarque:Pour plus de commodité, vous pouvez également récupérer la valeur actuelle de configuration avec un UserManager, en appelant UserManager.getApplicationRestrictions() Cette méthode se comporte exactement identique à RestrictionsManager.getApplicationRestrictions().

La méthode getApplicationRestrictions() nécessite de lire des données à partir du stockage de données. Par conséquent, avec parcimonie. N'appelez pas cette méthode chaque fois que vous devez de connaître la configuration actuelle. Vous devez l'appeler une seule fois lorsque votre application démarre ou reprend, et met en cache le bundle de configurations gérées récupéré. Ensuite, écoutez pour l'intent ACTION_APPLICATION_RESTRICTIONS_CHANGED afin de savoir si la configuration lorsque votre application est active, comme décrit dans la section Écouter les modifications de configuration gérée

Lire et appliquer des configurations gérées

La méthode getApplicationRestrictions() renvoie un Bundle. contenant une paire clé-valeur pour chaque configuration définie. La sont toutes de type Boolean, int, String et String[]. Une fois que vous avez des configurations gérées Bundle, vous pouvez vérifier de configuration avec les méthodes Bundle standards pour ces types de données, tels que getBoolean() ou getString()

Remarque:Les configurations gérées Bundle contient un élément pour chaque configuration qui a été explicitement définie par un un fournisseur de configurations gérées. Toutefois, vous ne pouvez pas supposer qu'un sera présente dans le bundle simplement parce que vous avez défini dans le fichier XML des configurations gérées.

Il appartient à votre application de prendre les mesures appropriées en fonction de la situation et les paramètres de configuration gérée. Par exemple, si votre application dispose d'un spécifiant s'il peut télécharger des données au réseau mobile et que la configuration est false, vous devez désactiver le téléchargement de données, sauf si L'appareil dispose d'une connexion Wi-Fi, comme illustré dans l'exemple de code suivant:

Kotlin

val appCanUseCellular: Boolean =
        if (appRestrictions.containsKey("downloadOnCellular")) {
            appRestrictions.getBoolean("downloadOnCellular")
        } else {
            // cellularDefault is a boolean using the restriction's default value
            cellularDefault
        }

if (!appCanUseCellular) {
    // ...turn off app's cellular-download functionality
    // ...show appropriate notices to user
}

Java

boolean appCanUseCellular;

if (appRestrictions.containsKey("downloadOnCellular")) {
    appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular");
} else {
    // cellularDefault is a boolean using the restriction's default value
    appCanUseCellular = cellularDefault;
}

if (!appCanUseCellular) {
    // ...turn off app's cellular-download functionality
    // ...show appropriate notices to user
}

Pour appliquer plusieurs restrictions imbriquées, consultez la page le bundle_array entrée de restriction en tant que collection d'objets Parcelable et caster en tant que Bundle. Dans cet exemple, la configuration de chaque VPN les données sont analysées et utilisées pour créer une liste des options de connexion au serveur:

Kotlin

// VpnConfig is a sample class used store config data, not defined
val vpnConfigs = mutableListOf<VpnConfig>()

val parcelables: Array<out Parcelable>? =
        appRestrictions.getParcelableArray("vpn_configuration_list")

if (parcelables?.isNotEmpty() == true) {
    // iterate parcelables and cast as bundle
    parcelables.map { it as Bundle }.forEach { vpnConfigBundle ->
        // parse bundle data and store in VpnConfig array
        vpnConfigs.add(VpnConfig()
                .setServer(vpnConfigBundle.getString("vpn_server"))
                .setUsername(vpnConfigBundle.getString("vpn_username"))
                .setPassword(vpnConfigBundle.getString("vpn_password")))
    }
}

if (vpnConfigs.isNotEmpty()) {
    // ...choose a VPN configuration or prompt user to select from list
}

Java

// VpnConfig is a sample class used store config data, not defined
List<VpnConfig> vpnConfigs = new ArrayList<>();

Parcelable[] parcelables =
    appRestrictions.getParcelableArray("vpn_configuration_list");

if (parcelables != null && parcelables.length > 0) {
    // iterate parcelables and cast as bundle
    for (int i = 0; i < parcelables.length; i++) {
        Bundle vpnConfigBundle = (Bundle) parcelables[i];
        // parse bundle data and store in VpnConfig array
        vpnConfigs.add(new VpnConfig()
            .setServer(vpnConfigBundle.getString("vpn_server"))
            .setUsername(vpnConfigBundle.getString("vpn_username"))
            .setPassword(vpnConfigBundle.getString("vpn_password")));
    }
}

if (!vpnConfigs.isEmpty()) {
    // ...choose a VPN configuration or prompt user to select from list
}

Écouter les modifications de configuration gérée

Chaque fois que les configurations gérées d'une application sont modifiées, le système déclenche Intent ACTION_APPLICATION_RESTRICTIONS_CHANGED. Votre application doit écouter cet intent afin que vous puissiez modifier le comportement de l'application lorsque les paramètres de configuration le changement.

Remarque:L'intent ACTION_APPLICATION_RESTRICTIONS_CHANGED n'est envoyé qu'aux écouteurs. enregistrés dynamiquement, pas pour les écouteurs déclarés dans le fichier manifeste de l'application.

Le code suivant montre comment enregistrer dynamiquement un broadcast receiver pour cet intent:

Kotlin

val restrictionsFilter = IntentFilter(Intent.ACTION_APPLICATION_RESTRICTIONS_CHANGED)

val restrictionsReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {

        // Get the current configuration bundle
        val appRestrictions = myRestrictionsMgr.applicationRestrictions

        // Check current configuration settings, change your app's UI and
        // functionality as necessary.
    }
}

registerReceiver(restrictionsReceiver, restrictionsFilter)

Java

IntentFilter restrictionsFilter =
    new IntentFilter(Intent.ACTION_APPLICATION_RESTRICTIONS_CHANGED);

BroadcastReceiver restrictionsReceiver = new BroadcastReceiver() {
  @Override public void onReceive(Context context, Intent intent) {

    // Get the current configuration bundle
    Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

    // Check current configuration settings, change your app's UI and
    // functionality as necessary.
  }
};

registerReceiver(restrictionsReceiver, restrictionsFilter);

Remarque:En règle générale, votre application n'a pas besoin d'être notifiée sur les modifications de configuration lorsqu'il est suspendu. Vous devez plutôt annuler l'enregistrement votre broadcast receiver lorsque l'application est mise en pause. Lorsque l'application est réactivée, vérifiez d'abord les configurations gérées actuelles (comme indiqué dans Vérifier les configurations gérées, puis enregistrer votre broadcast receiver pour vous assurer que vous êtes informé des modifications de configuration qui se produisent lorsque l'application est active.

Envoyer des commentaires sur la configuration gérée aux EMM

Après avoir appliqué les modifications de configuration gérées à votre application, il est recommandé d'informer les EMM l'état de la modification. Android est compatible avec une fonctionnalité appelée états d'application associés, que vous pouvez pour envoyer des commentaires chaque fois que votre application tente d'appliquer des modifications de configuration gérées. Ce les commentaires peuvent confirmer que votre application a bien défini des configurations gérées inclure un message d'erreur si votre application n'a pas pu appliquer les modifications spécifiées.

Les fournisseurs EMM peuvent récupérer ces commentaires et les afficher dans leurs consoles pour les services informatiques que les administrateurs peuvent consulter. Pour en savoir plus, consultez Envoyer des commentaires sur l'application aux EMM. des informations sur le sujet, y compris un guide détaillé sur l'ajout de la prise en charge des commentaires à votre application.

Autres exemples de code

Les ManagedConfigurations illustre davantage l'utilisation des API abordées sur cette page.