Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: work - Managed configuration bundles am: ef57498142

Browse Source 
am: 9684f2cd2f

Change-Id: Idaeea63ba30ecb86a4f60955bb4937357ba4fd1b
This commit is contained in:
Billy Lamberta
2016-07-21 15:21:52 +00:00
committed by android-build-merger
parent e9d58227bb 9684f2cd2f
commit c7cffa3e6a
1 changed files with 193 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
docs/html/work/managed-configurations.jd
View File

@@ -35,7 +35,10 @@ enterprise administrator to:</p>
</ul> </ul>
<p> <p>
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
<a href="https://developers.google.com/android/work/build-dpc"
>Build a Device Policy Controller</a> guide.
</p> </p>
<p class="note"> <p class="note">
@@ -96,11 +99,11 @@ enterprise administrator to:</p>
<p> <p>
Your app can support any managed configuration you want to define. You declare the Your app can support any managed configuration you want to define. You declare the
app's managed configurations in a <em>managed configurations file</em>, and declare the app's managed configurations in a <em>managed configurations file</em>, and declare
configurations file in the manifest. Creating a configurations file allows other the configurations file in the manifest. Creating a configurations file allows
apps to examine the managed configurations your app provides. Enterprise Mobility other apps to examine the managed configurations your app provides. Enterprise
Management (EMM) partners can read your app's configurations by using Google Mobility Management (EMM) partners can read your app's configurations by using
Play APIs. Google Play APIs.
</p> </p>
<p> <p>
@@ -137,6 +140,14 @@ enterprise administrator to:</p>
application. application.
</p> </p>
<p>
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.
</p>
<p> <p>
For example, suppose your app can be remotely configured to allow or forbid 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 it to download data over a cellular connection. Your app could have a
@@ -145,7 +156,7 @@ enterprise administrator to:</p>
<pre> <pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt; &lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;restrictions xmlns:android="http://schemas.android.com/apk/res/android" &gt; &lt;restrictions xmlns:android="http://schemas.android.com/apk/res/android"&gt;
&lt;restriction &lt;restriction
android:key="downloadOnCellular" android:key="downloadOnCellular"
@@ -157,11 +168,6 @@ enterprise administrator to:</p>
&lt;/restrictions&gt; &lt;/restrictions&gt;
</pre> </pre>
<p>
The supported types for the <code>android:restrictionType</code> element are
documented in the reference for {@link android.content.RestrictionsManager}.
</p>
<p> <p>
You use each configuration's <code>android:key</code> attribute to You use each configuration's <code>android:key</code> attribute to
read its value from a managed configuration bundle. For this reason, read its value from a managed configuration bundle. For this reason,
@@ -172,19 +178,145 @@ enterprise administrator to:</p>
<p class="note"> <p class="note">
<strong>Note:</strong> In a production app, <code>android:title</code> and <strong>Note:</strong> In a production app, <code>android:title</code> and
<code>android:description</code> should be drawn from a localized resource <code>android:description</code> should be drawn from a localized resource
file, as described in <a href= file, as described in
"{@docRoot}guide/topics/resources/localization.html">Localizing with <a href="{@docRoot}guide/topics/resources/localization.html"
Resources</a>. >Localizing with Resources</a>.
</p> </p>
<p> <p id="nested-restrictions">
The managed configuration provider can query the app to find details An app can define one or multiple nested restriction elements using
on the app's available configurations, including their description the restriction types
text. Configurations providers and enterprise administrators can {@link android.content.RestrictionEntry#TYPE_BUNDLE bundle} and
change your app's managed configurations at any time, even when the {@link android.content.RestrictionEntry#TYPE_BUNDLE_ARRAY bundle_array}.
app is not running. 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:
</p> </p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;restrictions xmlns:android="http://schemas.android.com/apk/res/android" &gt;
&lt;restriction
android:key="vpn_configuration_list"
android:restrictionType="bundle_array"&gt;
&lt;restriction
android:key="vpn_configuration"
android:restrictionType="bundle"&gt;
&lt;restriction
android:key="vpn_server"
android:restrictionType="string"/&gt;
&lt;restriction
android:key="vpn_username"
android:restrictionType="string"/&gt;
&lt;restriction
android:key="vpn_password"
android:restrictionType="string"/&gt;
&lt;/restriction&gt;
&lt;/restriction&gt;
&lt;/restrictions&gt;
</pre>
<p>
The supported types for the <code>android:restrictionType</code> element
are listed in <a href="#restriction-types">Table 1</a> and documented in
the reference for {@link android.content.RestrictionsManager} and
{@link android.content.RestrictionEntry}.
</p>
<p class="table-caption" id="restriction-types">
<strong>Table 1.</strong> Restriction entry types and usage.
</p>
<table>
<tbody>
<tr>
<th>Type</th>
<th>android:restrictionType</th>
<th>Typical usage</th>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_BOOLEAN TYPE_BOOLEAN}
</td>
<td><code>"bool"</code></td>
<td>
A boolean value, true or false.
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_STRING TYPE_STRING}
</td>
<td><code>"string"</code></td>
<td>
A string value, such as a name.
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_INTEGER TYPE_INTEGER}
</td>
<td><code>"integer"</code></td>
<td>
An integer with a value from
{@link java.lang.Integer#MIN_VALUE MIN_VALUE} to
{@link java.lang.Integer#MAX_VALUE MAX_VALUE}.
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_CHOICE TYPE_CHOICE}
</td>
<td><code>"choice"</code></td>
<td>
A string value, typically presented as a single-select list.
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_MULTI_SELECT TYPE_MULTI_SELECT}
</td>
<td><code>"multi-select"</code></td>
<td>
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.
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_NULL TYPE_NULL}
</td>
<td><code>"hidden"</code></td>
<td>
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.
</td>
</tr>
<tr>
<td>{@link android.content.RestrictionEntry#TYPE_BUNDLE TYPE_BUNDLE}</td>
<td><code>"bundle"</code></td>
<td>
Use this for storing {@link android.os.Bundle bundles} of
restrictions. Available in Android 6.0 (API level 23).
</td>
</tr>
<tr>
<td>
{@link android.content.RestrictionEntry#TYPE_BUNDLE_ARRAY TYPE_BUNDLE_ARRAY}
</td>
<td><code>"bundle_array"</code></td>
<td>
Use this for storing arrays of restriction
<a href="{@docRoot}reference/android/os/Bundle.html"
>bundles</a>. Available in Android 6.0 (API level 23).
</td>
</tr>
</tbody>
</table>
<h2 id="check-configuration"> <h2 id="check-configuration">
Check Managed Configurations Check Managed Configurations
</h2> </h2>
@@ -292,11 +424,10 @@ enterprise administrator to:</p>
<pre> <pre>
boolean appCanUseCellular; boolean appCanUseCellular;
if appRestrictions.containsKey("downloadOnCellular") { if (appRestrictions.containsKey("downloadOnCellular")) {
appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular"); appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular");
} else { } else {
// here, cellularDefault is a boolean set with the restriction's // cellularDefault is a boolean using the restriction's default value
// default value
appCanUseCellular = cellularDefault; appCanUseCellular = cellularDefault;
} }
@@ -305,6 +436,37 @@ if (!appCanUseCellular) {
// ...show appropriate notices to user // ...show appropriate notices to user
}</pre> }</pre>
<p>
To apply multiple <a href="#nested-restrictions">nested restrictions</a>, 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:
</p>
<pre>
// VpnConfig is a sample class used store config data, not defined
List&lt;VpnConfig&gt; vpnConfigs = new ArrayList&lt;&gt;();
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
}</pre>
<h2 id="listen-configuration"> <h2 id="listen-configuration">
Listen for Managed Configuration Changes Listen for Managed Configuration Changes
</h2> </h2>