将应用反馈发送到 EMM

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

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

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

键控应用状态的组件

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

  • 键：应用状态的唯一标识符。最多 100 个字符。
  • 消息：描述应用状态的可选消息。最多 1000 个字符。注意：通常，消息应明显短于此。
  • 数据：供 EMM 使用的可选机器可读值，允许 IT 管理员根据该值设置警报或过滤器。例如，如果数据字段battery_percentage < 10，则 IT 管理员可以设置警报。最多 1000 个字符。

  • 严重程度： 应用状态的严重程度。允许的值为 SEVERITY_ERROR 和 SEVERITY_INFO（默认值）。仅在组织需要采取措施修复的真正错误情况下，才将严重程度设置为 SEVERITY_ERROR。
  • 时间戳： 设置键控应用状态时，会自动附带自纪元以来的毫秒级时间戳。

发送托管配置反馈

如果您的应用支持 托管配置，则建议发送键控应用状态作为更新 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 提供商还应将任何接收到的具有 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 可以停止在其控制台中标记错误。
  • 对于后续状态，请使用与返回错误的初始状态相同的 键 并将严重程度设置为 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);

测试键控应用状态

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