向 EMM 发送应用反馈

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

面向企业组织的应用能够以键控应用状态的形式向 EMM 发送反馈。一些 API 可供 EMM 用来检索键控应用状态数据,这些数据随后可在其 EMM 控制台中显示。IT 管理员可通过这种沟通渠道接收有关其所管理的设备上安装的应用的状态的反馈。

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

键控应用状态的组件

键控应用状态由以下因素组成:

  • :应用状态的唯一标识符。不得超过 100 个字符。
  • 消息:说明应用状态的可选消息。最多 1,000 个字符。注意:通常,消息的长度应明显短于该值。
  • 数据:可选的机器可读值,适用于 EMM,以允许 IT 管理员根据该值设置提醒或过滤条件。例如,如果数据字段为 battery_percentage < 10,IT 管理员可以设置提醒。最多 1,000 个字符。
  • 严重级别 :应用状态的严重级别。允许的值包括 SEVERITY_ERRORSEVERITY_INFO(默认值)。只有在发现组织需要采取措施来修正真实错误情况时,才将严重级别设置为 SEVERITY_ERROR
  • 时间戳 :设置键控应用状态后,系统会自动发送该状态,其中包含时间戳(以毫秒为单位,从纪元开始算起)。

发送托管配置反馈

如果您的应用支持托管配置,则建议通过发送键控应用状态来向 IT 管理员更新所设置的配置的状态。以下示例工作流介绍了一种方法。

托管配置的键控应用状态
  1. IT 管理员使用 EMM 控制台为完全受管设备工作资料内安装的应用设置和发送托管配置。 例如:
    • 音量:“50%”
    • 币种:“USDD”
  2. 应用尝试应用配置。音量已成功设置为 50%,但货币代码无效,无法应用。
  3. 应用会根据每项配置的状态设置一个键控应用状态。每个键控应用状态都包含一个唯一键以及一条包含状态详情的消息。我们建议您尽可能匹配托管配置键。 例如:
    消息 严重程度 时间戳
    volume 设置为 50% SEVERITY_INFO 1554461130
    currency 无法识别“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_LENGTHMAX_MESSAGE_LENGTHMAX_DATA_LENGTH 中定义的限制范围内。
  • 单个 setStatessetStatesImmediate 调用的总大小不得超过 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);

测试键控应用状态

如需详细了解测试说明,请参阅测试应用反馈