设置托管配置

如果您正在开发企业市场应用，您可能需要满足组织政策设定的特定要求。托管配置（以前称为 应用限制）允许组织的 IT 管理员远程指定应用的设置。此功能对于部署到工作资料的组织批准的应用特别有用。

例如，组织可能要求批准的应用允许 IT 管理员执行以下操作

允许或阻止网络浏览器的 URL
配置应用是允许通过蜂窝网络同步内容，还是只允许通过 Wi-Fi 同步
配置应用的电子邮件设置

本指南展示了如何在应用中实现托管配置设置。要查看包含托管配置的示例应用，请参阅 ManagedConfigurations。如果您是企业移动管理 (EMM) 开发者，请参阅 Android Management API 指南。

注意：出于历史原因，这些配置设置称为限制，并通过使用此术语的文件和类（如 RestrictionsManager）来实现。然而，这些限制实际上可以实现各种配置选项，而不仅仅是应用功能的限制。

远程配置概述

应用定义了 IT 管理员可以远程设置的托管配置选项。这些是可以由托管配置提供者更改的任意设置。如果您的应用在工作资料中运行，IT 管理员可以更改您应用的托管配置。

托管配置提供者是同一设备上运行的另一个应用。此应用通常由 IT 管理员控制。IT 管理员将配置更改通知给托管配置提供者应用。该应用反过来会更改您应用上的配置。

要提供外部管理的配置

在您的应用清单中声明托管配置。这样做可以允许 IT 管理员通过 Google Play API 读取应用的配置。
每当应用恢复时，使用 RestrictionsManager 对象检查当前的托管配置，并更改您应用的 UI 和行为以符合这些配置。
监听 ACTION_APPLICATION_RESTRICTIONS_CHANGED intent。当您收到此广播时，检查 RestrictionsManager 以查看当前的托管配置是什么，并对您的应用行为进行任何必要的更改。

定义托管配置

您的应用可以支持您想要定义的任何托管配置。您在一个托管配置文件中声明应用的托管配置，并在清单中声明配置文件。创建配置文件允许其他应用检查您的应用提供的托管配置。EMM 合作伙伴可以使用 Google Play API 读取您应用的配置。

要定义应用的远程配置选项，请将以下元素放在清单的 <application> 元素中

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

在应用的 res/xml 目录中创建一个名为 app_restrictions.xml 的文件。该文件的结构在 RestrictionsManager 的参考中进行了描述。该文件有一个顶层 <restrictions> 元素，其中包含应用拥有的每个配置选项的一个 <restriction> 子元素。

注意：不要创建托管配置文件的本地化版本。您的应用只允许有一个托管配置文件，因此配置在所有区域设置中对您的应用都是一致的。

在企业环境中，EMM 通常会使用托管配置模式为 IT 管理员生成一个远程控制台，以便管理员可以远程配置您的应用。

托管配置提供者可以查询应用以查找有关应用可用配置的详细信息，包括其描述文本。配置提供者和 IT 管理员可以随时更改您应用的托管配置，即使应用未运行。

例如，假设您的应用可以远程配置，以允许或禁止其通过蜂窝连接下载数据。您的应用可以包含一个像这样的 <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>

您可以使用每个配置的 android:key 属性从托管配置 Bundle 中读取其值。因此，每个配置必须有一个唯一的键字符串，并且该字符串不能进行本地化。它必须指定为字符串字面量。

注意：在生产应用中，android:title 和 android:description 应从本地化资源文件中提取，如使用资源进行本地化中所述。

应用使用 bundle_array 中的 Bundle 来定义限制。例如，一个具有多个 VPN 连接选项的应用可以将每个 VPN 服务器配置定义在一个 bundle 中，多个 Bundle 组合在一起形成一个 Bundle 数组

<?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>

支持的 android:restrictionType 元素类型列在表 1 中，并在 RestrictionsManager 和 RestrictionEntry 的参考文档中进行了详细说明。

表 1. 限制条目类型和用法。

类型	android:restrictionType	典型用法
`TYPE_BOOLEAN`	`"bool"`	布尔值，true 或 false。
`TYPE_STRING`	`"string"`	字符串值，例如名称。
`TYPE_INTEGER`	`"integer"`	整数，其值介于 `MIN_VALUE` 和 `MAX_VALUE` 之间。
`TYPE_CHOICE`	`"choice"`	从 `android:entryValues` 中选择的字符串值，通常显示为单选列表。
`TYPE_MULTI_SELECT`	`"multi-select"`	从 `android:entryValues` 中选择的字符串数组。用于呈现多选列表，其中可以选择多个条目，例如用于选择要加入白名单的特定标题。
`TYPE_NULL`	`"hidden"`	隐藏的限制类型。对于需要在后台传输但不能在 UI 中呈现给用户的信息，使用此类型。存储一个字符串值。
`TYPE_BUNDLE_ARRAY`	`"bundle_array"`	用于存储限制 `bundles` 的数组。在 Android 6.0（API 级别 23）及更高版本中可用。

注意： android:entryValues 是机器可读的，不能本地化。使用 android:entries 呈现可本地化的用户可读值。每个条目在 android:entryValues 中必须有一个对应的索引。

检查托管配置

当其他应用更改其配置设置时，您的应用不会自动收到通知。相反，您需要在应用启动或恢复时检查托管配置是什么，并监听系统 intent 以了解配置是否在应用运行时发生更改。

要了解当前的配置设置，您的应用使用 RestrictionsManager 对象。您的应用应在以下时间检查当前的托管配置

应用启动或恢复时，在其 onResume() 方法中
应用收到配置更改通知时，如监听托管配置更改中所述

要获取 RestrictionsManager 对象，使用 getActivity() 获取当前 Activity，然后调用该 Activity 的 Activity.getSystemService() 方法

Kotlin

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

Java

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

获得 RestrictionsManager 后，您可以通过调用其 getApplicationRestrictions() 方法获取当前的配置设置

Kotlin

var appRestrictions: Bundle = myRestrictionsMgr.applicationRestrictions

Java

Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

注意：为方便起见，您还可以通过 UserManager 获取当前的配置，方法是调用 UserManager.getApplicationRestrictions()。此方法的行为与 RestrictionsManager.getApplicationRestrictions() 完全相同。

方法 getApplicationRestrictions() 需要从数据存储中读取，因此应谨慎使用。不要在每次需要了解当前配置时都调用此方法。相反，您应在应用启动或恢复时调用一次，并缓存获取的托管配置 Bundle。然后监听 ACTION_APPLICATION_RESTRICTIONS_CHANGED intent，以了解配置是否在应用活动时发生更改，如监听托管配置更改中所述。

读取和应用托管配置

方法 getApplicationRestrictions() 返回一个 Bundle，其中包含每个已设置配置的键值对。所有值都是 Boolean、int、String 和 String[] 类型。拥有托管配置 Bundle 后，您可以使用这些数据类型的标准 Bundle 方法（例如 getBoolean() 或 getString()）检查当前配置设置。

注意：托管配置 Bundle 包含托管配置提供者明确设置的每个配置的一项。但是，您不能因为您在托管配置 XML 文件中定义了默认值就假设配置会存在于 Bundle 中。

您的应用需要根据当前的托管配置设置采取适当的操作。例如，如果您的应用有一个配置指定是否可以通过蜂窝连接下载数据，并且您发现该配置设置为 false，则您必须禁用数据下载，除非设备连接到 Wi-Fi，如以下示例代码所示

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
}

要应用多个嵌套限制，请将 bundle_array 限制条目读取为 Parcelable 对象的集合，并将其转换为 Bundle。在此示例中，解析每个 VPN 的配置数据并用于构建服务器连接选项列表

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
}

监听托管配置更改

每当应用的托管配置发生更改时，系统会触发 ACTION_APPLICATION_RESTRICTIONS_CHANGED intent。您的应用必须监听此 intent，以便在配置设置更改时更改应用的行为。

注意： ACTION_APPLICATION_RESTRICTIONS_CHANGED intent 仅发送给动态注册的监听器，而不是发送给在应用清单中声明的监听器。

以下代码展示了如何为此 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);

注意：通常情况下，您的应用在暂停时无需接收配置更改的通知。相反，您应该在应用暂停时取消注册您的广播接收器。当应用恢复时，您首先检查当前的托管配置（如检查托管配置中所述），然后注册您的广播接收器，以确保您收到应用活动期间发生的配置更改通知。

向 EMM 发送托管配置反馈

在对您的应用应用托管配置更改后，最佳实践是通知 EMM 更改的状态。Android 支持一项称为“键控应用状态”的功能，您可以使用它在每次应用尝试应用托管配置更改时发送反馈。此反馈可以作为确认您的应用成功设置了托管配置的凭证，或者如果您的应用未能应用指定的更改，则可以包含一条错误消息。

EMM 提供商能够检索此反馈并将其显示在他们的控制台中供 IT 管理员查看。有关此主题的更多信息，包括关于如何向您的应用添加反馈支持的详细指南，请参阅向 EMM 发送应用反馈。

其他代码示例

ManagedConfigurations 样本进一步演示了此页面涵盖的 API 的用法。

在个人资料上允许/阻止应用

第三方应用商店可能对使用托管配置表示兴趣，以便以可靠的方式将应用阻止列表或允许列表应用于个人资料和私密空间消费者功能，后者是用户用于存放敏感应用的额外个人空间。如果您开发用于企业用途的应用商店，并且希望使用此功能，请提交此表单以表明兴趣，并在表单中选择 Interest in 3P app store allowlisting 作为 Reason for Response。

设置托管配置 利用集合保持井然有序 根据您的偏好保存内容并进行分类。

远程配置概述

定义托管配置

检查托管配置

Kotlin

Java

Kotlin

Java

读取和应用托管配置

Kotlin

Java

Kotlin

Java

监听托管配置更改

Kotlin

Java

向 EMM 发送托管配置反馈

其他代码示例

在个人资料上允许/阻止应用

设置托管配置