向 EMM 发送应用反馈

企业移动管理 (EMM) 提供商为组织提供解决方案 管理 Android 设备及其上安装的应用。这些解决方案分别是 通常以网络控制台的形式提供，称为 EMM 控制台。使用 EMM IT 管理员可代表管理员执行设备和应用管理任务， 组织。

面向企业组织的应用可以通过以下形式向 EMM 发送反馈： 键控应用状态。API 可用于 EMM 检索键控应用状态数据 然后显示在 EMM 控制台中此沟通渠道 可让 IT 管理员接收有关以下设备上所安装应用程序的状态的反馈 管理的设备

例如，电子邮件客户端应用可以使用键控应用状态来确认 成功配置账户，在发生同步错误时报告，或发送任何 应用开发者认为合适的其他状态更新。

键控应用状态的组成部分

键控应用状态由以下几个部分组成：

• 键：应用状态的唯一标识符。不得超过 100 个字符。
• 消息：描述应用状态的可选消息。最大值：1000 字符。注意：邮件通常应该比这短很多。
• 数据：（可选）机器可读值，用于 EMM，供 IT 管理员使用 设置基于该值的提醒或过滤器。例如，IT 管理员可以 设置提醒，如果数据字段battery_percentage < 10.最大值：1000 字符。
• 严重性 ：应用状态的严重性。允许的值包括 SEVERITY_ERROR 和SEVERITY_INFO （默认）。仅将严重级别设置为 SEVERITY_ERROR 以了解组织需要采取措施修正的真正错误情况。
• 时间戳 ：设置键控应用状态后，系统会自动随同 时间戳（以毫秒为单位，从 Epoch 起算）。

发送有关受管配置的反馈

如果您的应用支持受管配置， 建议通过发送关键应用状态来更新 其所设置的配置的状态。以下示例工作流介绍了 实现这一目的的方法之一。

1. IT 管理员可使用 EMM 控制台为 全托管式设备上安装的应用 或工作资料中。 例如：
   • 音量：“50%”
   • 币种：“USDD”
2. 应用会尝试应用配置。已成功设置音量 到 50%，但货币代码无效，无法应用。
3. 应用会根据每项配置的状态设置键控应用状态。 每个键控应用状态都包含一个唯一键和一条包含 状态。我们建议尽可能匹配托管配置密钥。 例如：

   键	消息	严重程度	时间戳
   volume	设置为 50%	SEVERITY_INFO	1554461130
   currency	币种“USDD”无法识别	SEVERITY_ERROR	1554461130

4. EMM 提供商会检索由应用设置的键控应用状态，并显示 管理这些服务例如：

   配置	状态	请采取行动	时间
   音量	设置为 50%	否	2019 年 4 月 5 日；上午 10:45:30
   币种	错误：货币“USDD”无法识别。	是	2019 年 4 月 5 日；上午 10:45:30

   EMM 提供商还应使用 SEVERITY_ERROR IT 管理员。IT 管理员可以在 EMM 控制台中查看这些信息， 采取措施纠正其所设置配置中出现的任何错误。

报告已解决的错误

错误解决后，立即将后续应用状态发送到 防止 EMM 无限期地显示错误消息。此跟进邮件 应包含：

• 相同的键 作为初始错误消息。
• 严重级别为 SEVERITY_INFO， 这表示状态既不处于错误状态 要求组织采取进一步的措施。

向应用添加对键控应用状态的支持

以下步骤介绍了如何在您的应用中集成键控应用状态。

第 1 步：将 Google 的 Maven 制品库添加到 settings.gradle 文件中

在项目的 settings.gradle 中将 Google 的 Maven 制品库添加为仓库位置 如下所示：

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
       google()
  }
}

第 2 步：将企业反馈库添加到模块级 build.gradle 文件中

将以下依赖项添加到您的模块级 build.gradle 文件：

dependencies {
    implementation 'androidx.enterprise:enterprise-feedback:1.0.0'
}

第 3 步：获取 KeyedAppStatesReporter 的实例

在 onCreate() 方法中，获取并存储 KeyedAppStatesReporter。 这样，您的应用和 EMM 提供商之间就可以建立通信渠道。

Kotlin

val reporter = KeyedAppStatesReporter.create(context)

Java

KeyedAppStatesReporter reporter = KeyedAppStatesReporter.create(context);

第 4 步：创建键控应用状态的集合

创建键控应用状态时，请遵循下面列出的最佳实践：

• 切勿在状态中包含个人身份信息 (PII)，因为键控应用的状态并非如此 适合存储敏感数据。
• 使键控应用状态保持在 MAX_KEY_LENGTH、 MAX_MESSAGE_LENGTH, 和MAX_DATA_LENGTH。
• 单个 setStates 或 setStatesImmediate 调用的总大小上限为 300 KB（大约每天可存储的总数的 1/3）。超过此值将导致未定义的行为。
• 仅将状态的严重级别设置为 SEVERITY_ERROR 如果存在需要组织采取措施来修复的条件。
• 在发送包含错误的应用状态时，请确保同时发送 解决错误时发送跟进状态，以便 EMM 可以停止标记 。
• 对于后续状态，请使用相同的 key 作为 初始状态，它返回了错误并将严重性设置为 SEVERITY_INFO。

以下代码段会创建键控应用状态的集合：

Kotlin

    val states = hashSetOf(KeyedAppState.builder()
             .setKey("key")
             .setSeverity(KeyedAppState.SEVERITY_INFO)
             .setMessage("message")
             .setData("data")
             .build())
    

Java

    Collection states = new HashSet<>();
    states.add(KeyedAppState.builder()
     .setKey("key")
     .setSeverity(KeyedAppState.SEVERITY_INFO)
     .setMessage("message")
     .setData("data")
     .build());
    

第 5 步：设置键控应用状态

注意：您每天最多可以为您的应用设置 500 个唯一密钥。我们没有 限制了您可以为每个唯一键设置的状态数量。

setStates() 方法立即向 Play 商店应用（软件包名称： com.android.vending）以及 设备或工作资料

Kotlin

keyedAppStatesReporter.setStates(states)

Java

keyedAppStatesReporter.setStates(states);

测试键控应用状态

如需查看详细的测试说明，请参阅测试应用反馈。