向 EMM 发送应用反馈

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

面向企业组织的应用可以以键控应用状态的形式向 EMM 发送反馈。EMM 可以通过 API 检索键控应用状态数据，然后将其显示在其 EMM 控制台中。此通信渠道允许 IT 管理员接收有关他们所管理设备上安装的应用状态的反馈。

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

键控应用状态的组成部分

键控应用状态包括以下内容：

  • 键： 应用状态的唯一标识符。最长 100 个字符。
  • 消息： 描述应用状态的可选消息。最长 1000 个字符。注意：消息通常应远短于此长度。
  • 数据： 供 EMM 使用的可选机器可读值，允许 IT 管理员根据该值设置警报或过滤器。例如，如果数据字段 battery_percentage < 10，IT 管理员可以设置警报。最长 1000 个字符。
  • 严重性： 应用状态的严重性。允许的值为 SEVERITY_ERROR 和 SEVERITY_INFO（默认值）。仅当组织需要采取措施修复的真正错误情况时，才将严重性设置为 SEVERITY_ERROR。
  • 时间戳： 设置键控应用状态时，它会自动附带一个自 epoch 以来的毫秒时间戳。

发送代管式配置反馈

如果您的应用支持代管式配置，建议使用发送键控应用状态的方式来更新 IT 管理员有关其设置的配置状态。以下示例工作流程描述了一种实现方式。

keyed app states for managed configurations
  1. IT 管理员使用其 EMM 控制台为安装在全代管设备上或工作资料中的应用设置和发送代管式配置。例如：
    • 音量：“50%”
    • 货币：“USDD”
  2. 应用尝试应用配置。音量成功设置为 50%，但货币代码无效且无法应用。
  3. 根据每个配置的状态，应用设置一个键控应用状态。每个键控应用状态包含一个唯一键和一条包含状态详细信息的消息。我们建议尽可能匹配代管式配置键。例如：
    键 消息 严重性 时间戳
    音量 设置为 50% SEVERITY_INFO 1554461130
    货币 货币“USDD”无法识别 SEVERITY_ERROR 1554461130
  4. EMM 供应商检索应用设置的键控应用状态，并在其 EMM 控制台中显示。例如：
    配置 状态 需要采取行动 时间
    音量 设置为 50% 否 2019 年 4 月 5 日；上午 10:45:30
    货币 错误：货币“USDD”无法识别。 是 2019 年 4 月 5 日；上午 10:45:30

    EMM 供应商还应向 IT 管理员明确标记任何接收到的 SEVERITY_ERROR 状态。IT 管理员可以在其 EMM 控制台中查看信息，并采取行动纠正其设置的配置中的任何错误。

报告已解决的错误

错误解决后，立即发送后续应用状态，以防止 EMM 无限期地显示错误消息。此后续状态应包括：

  • 与初始错误消息相同的 键。
  • 严重性为 SEVERITY_INFO，表示状态不处于错误条件，不需要组织采取任何进一步行动。

为您的应用添加键控应用状态支持

以下步骤描述了如何将键控应用状态集成到您的应用中。

步骤 1：将 Google 的 Maven 仓库添加到您的 settings.gradle 文件中

将 Google 的 Maven 仓库作为仓库位置添加到项目的 settings.gradle 文件中，如下所示：

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 停止在其控制台中标记错误。
  • 对于后续状态，使用与返回错误的初始状态相同的 键，并将严重性设置为 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：设置键控应用状态

setStates() 方法会立即将键控应用状态发送到 Play 商店应用（软件包名称：com.android.vending，如果已安装在设备上），以及设备或工作资料的任何管理员。

Kotlin

keyedAppStatesReporter.setStates(states)

Java

keyedAppStatesReporter.setStates(states);

测试键控应用状态

有关详细测试说明，请参阅测试应用反馈。