将应用反馈发送到 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：设置键控应用状态

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

Kotlin

keyedAppStatesReporter.setStates(states)

Java

keyedAppStatesReporter.setStates(states);

测试键控应用状态

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