- This guide shows how to implement these configuration settings in your app. + This guide shows how to implement managed configuration settings in + your app. If you're an EMM developer, refer to the + Build a Device Policy Controller guide.
@@ -71,8 +74,8 @@ enterprise administrator to:
Your app can support any managed configuration you want to define. You declare the - app's managed configurations in a managed configurations file, and declare the - configurations file in the manifest. Creating a configurations file allows other - apps to examine the managed configurations your app provides. Enterprise Mobility - Management (EMM) partners can read your app's configurations by using Google - Play APIs. + app's managed configurations in a managed configurations file, and declare + the configurations file in the manifest. Creating a configurations file allows + other apps to examine the managed configurations your app provides. Enterprise + Mobility Management (EMM) partners can read your app's configurations by using + Google Play APIs.
@@ -137,6 +140,14 @@ enterprise administrator to:
application. ++ The managed configuration provider can query the app to find details + on the app's available configurations, including their description + text. The configurations provider and enterprise administrator can + change your app's managed configurations at any time, even when the + app is not running. +
+For example, suppose your app can be remotely configured to allow or forbid it to download data over a cellular connection. Your app could have a @@ -145,7 +156,7 @@ enterprise administrator to:
<?xml version="1.0" encoding="utf-8"?>
-<restrictions xmlns:android="http://schemas.android.com/apk/res/android" >
+<restrictions xmlns:android="http://schemas.android.com/apk/res/android">
<restriction
android:key="downloadOnCellular"
@@ -157,11 +168,6 @@ enterprise administrator to:
</restrictions>
-
- The supported types for the android:restrictionType element are
- documented in the reference for {@link android.content.RestrictionsManager}.
-
You use each configuration's android:key attribute to
read its value from a managed configuration bundle. For this reason,
@@ -172,19 +178,145 @@ enterprise administrator to:
Note: In a production app, android:title and
android:description should be drawn from a localized resource
- file, as described in Localizing with
- Resources.
+ file, as described in
+ Localizing with Resources.
- The managed configuration provider can query the app to find details - on the app's available configurations, including their description - text. Configurations providers and enterprise administrators can - change your app's managed configurations at any time, even when the - app is not running. +
+ An app can define one or multiple nested restriction elements using + the restriction types + {@link android.content.RestrictionEntry#TYPE_BUNDLE bundle} and + {@link android.content.RestrictionEntry#TYPE_BUNDLE_ARRAY bundle_array}. + For example, an app with multiple VPN connection options could define + each VPN server configuration in a bundle, with multiple bundles grouped + together in a bundle array:
++<?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> ++ +
+ The supported types for the android:restrictionType element
+ are listed in Table 1 and documented in
+ the reference for {@link android.content.RestrictionsManager} and
+ {@link android.content.RestrictionEntry}.
+
+ Table 1. Restriction entry types and usage. +
+| Type | +android:restrictionType | +Typical usage | +
|---|---|---|
| + {@link android.content.RestrictionEntry#TYPE_BOOLEAN TYPE_BOOLEAN} + | +"bool" |
+ + A boolean value, true or false. + | +
| + {@link android.content.RestrictionEntry#TYPE_STRING TYPE_STRING} + | +"string" |
+ + A string value, such as a name. + | +
| + {@link android.content.RestrictionEntry#TYPE_INTEGER TYPE_INTEGER} + | +"integer" |
+ + An integer with a value from + {@link java.lang.Integer#MIN_VALUE MIN_VALUE} to + {@link java.lang.Integer#MAX_VALUE MAX_VALUE}. + | +
| + {@link android.content.RestrictionEntry#TYPE_CHOICE TYPE_CHOICE} + | +"choice" |
+ + A string value, typically presented as a single-select list. + | +
| + {@link android.content.RestrictionEntry#TYPE_MULTI_SELECT TYPE_MULTI_SELECT} + | +"multi-select" |
+ + Use this for presenting a multi-select list where more than + one entry can be selected, such as for choosing specific + titles to white-list. + | +
| + {@link android.content.RestrictionEntry#TYPE_NULL TYPE_NULL} + | +"hidden" |
+ + Hidden restriction type. Use this type for information that + needs to be transferred across but shouldn't be presented to + the user in the UI. Stores a single string value. + | +
| {@link android.content.RestrictionEntry#TYPE_BUNDLE TYPE_BUNDLE} | +"bundle" |
+ + Use this for storing {@link android.os.Bundle bundles} of + restrictions. Available in Android 6.0 (API level 23). + | +
| + {@link android.content.RestrictionEntry#TYPE_BUNDLE_ARRAY TYPE_BUNDLE_ARRAY} + | +"bundle_array" |
+ + Use this for storing arrays of restriction + bundles. Available in Android 6.0 (API level 23). + | +
boolean appCanUseCellular;
-if appRestrictions.containsKey("downloadOnCellular") {
+if (appRestrictions.containsKey("downloadOnCellular")) {
appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular");
} else {
- // here, cellularDefault is a boolean set with the restriction's
- // default value
+ // cellularDefault is a boolean using the restriction's default value
appCanUseCellular = cellularDefault;
}
@@ -305,6 +436,37 @@ if (!appCanUseCellular) {
// ...show appropriate notices to user
}
++ To apply multiple nested restrictions, read + the {@link android.content.RestrictionEntry#TYPE_BUNDLE_ARRAY bundle_array} + restriction entry as a collection of {@link android.os.Parcelable} objects + and cast as a {@link android.os.Bundle}. In this example, each VPN's configuration + data is parsed and used to build a list of server connection choices: +
+ +
+// 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
+}
+