将现有设备迁移到 AMAPI

已由自定义 DPC 管理的设备可以迁移到 Android Device Policy (ADP)，并利用 Android Management API。

前提条件

  • 设备已由您的 EMM 通过自定义 DPC 进行管理。
  • 您的自定义 DPC 已与 AMAPI SDK 集成。
  • 设备已通过 Google Play EMM API 完成注册。
  • 设备属于 Google Play 企业版账号集。
  • 设备搭载 Android 9 或更高版本。
  • 如果公司自有设备上设有工作资料，则该设备必须搭载 Android 11 或更高版本。

在自定义 DPC 中与 AMAPI SDK 集成

迁移过程需要自定义 DPC 应用集成 AMAPI SDK。如需详细了解此库以及如何将其添加到应用中，请参阅 AMAPI SDK 集成指南。

迁移设备的步骤

  1. 设置旨在供设备在迁移到 AMAPI 后使用的政策。为了提供最佳用户体验，此值应与 DPC 在设备上已强制执行的政策相当。AMAPI 中的政策必须属于与设备在 Play EMM API 中已归属的企业相同的企业。请注意，在 AMAPI 和 Play EMM API 中，指定企业的名称相同。
  2. 通过调用 enterprises.migrationTokens.create 为设备创建迁移令牌。
  3. 将此迁移令牌的 value 发送给您的自定义 DPC。
  4. 使用 Play EMM API 确保 Android Device Policy 已安装在设备上。
  5. 使用 DpcMigrationClientFactory 创建 DpcMigrationClient
  6. 在 DpcMigrationClient 上，调用 migrateDeviceManagementToAndroidManagementApi 方法。至此，迁移过程全部完成。
  7. deviceState 更改为 ACTIVE，您将通过 Pub/Sub 渠道收到 STATUS_REPORT 消息。

迁移完成后，调用应用会失去其设备所有者或资料所有者权限，因为这些权限已转移到 Android Device Policy。此流程可用以下序列图表示：

设备政策控制器 (DPC) 迁移序列图

注意：设备必须连接到互联网才能开始迁移。此流程旨在确保在迁移过程中即使发生网络断开，也能正常完成迁移，因此需要网络连接的关键操作会在实际将设备所有者或资料所有者权限从 DPC 转移到 Android Device Policy 之前完成。

迁移令牌

EMM 服务器会请求迁移令牌，以表明打算迁移由自定义设备政策控制器管理的特定设备。迁移令牌可一直使用，直到迁移成功完成或令牌过期。

自定义 DPC 集成

首先，您需要创建一个 DpcMigrationRequest，并将令牌（如果需要，还需将配置的 WLAN 网络列表）传递给其构建器：

// Create a DpcMigrationRequest
DpcMigrationRequest request =
        DpcMigrationRequest.builder()
            .setMigrationToken(token)
            .build();

然后，您可以使用 DpcMigrationClient 获取 migrateDeviceManagementToAndroidManagementApi 并开始迁移流程：

// Create a DpcMigrationClient
DpcMigrationClient dpcMigrationClient = DpcMigrationClientFactory.create(context);
try {
  // Use helper function to retrieve Admin component name
  var adminComponentName = getAdminComponent(context);

  ListenableFuture<DpcMigrationAttempt> futureAttempt =
          dpcMigrationClient.migrateDeviceManagementToAndroidManagementApi(
              new ComponentName(context, DpcMigrationNotificationReceiver.class),
              adminComponentName,
              request);
  // handle futureAttempt
} catch (RuntimeException e) {
  // send failure feedback: "Error: " + e
}

设置 NotificationReceiverService 并跟踪迁移

在自定义 DPC 中实现 NotificationReceiverService。

迁移过程通过 DpcMigrationAttempt 在设备上进行跟踪。

您可以直接使用 migrateDeviceManagementToAndroidManagementApi 返回的迁移尝试，也可以使用 getMigrationAttempt 和 listMigrationAttempts 方法来获取和列出迁移尝试。

// Passing an empty name, we retrieve the last attempt
var request = GetDpcMigrationAttemptRequest.builder().build();

var attempt = client.getMigrationAttempt(request);

您可以选择使用 NotificationReceiverService 设置 DpcMigrationListener，以监听 DpcMigrationAttempt 的状态更新。

// DpcMigrationNotificationReceiver for callback handling
public class DpcMigrationNotificationReceiver extends NotificationReceiverService
    implements DpcMigrationListener {

  @Override
  protected DpcMigrationListener getDpcMigrationListener() {
    return this;
  }

  @Override
  public void onMigrationStateChanged(DpcMigrationAttempt migrationAttempt) {
    // send success feedback
  }
}

处理 Wi-Fi 网络

如果存在由自定义 DPC 管理的 Wi-Fi 网络，AMAPI ONC 政策应与这些网络的配置相匹配，以便 AMAPI 顺利开始管理这些网络。DPC 迁移与 Wi-Fi 管理的互动因管理模式而异。

全托管式设备和公司自有设备上的工作资料

在迁移期间，Android Device Policy 会假设在政策中配置的任何 Wi-Fi 网络（如果其 SSID 和安全类型与设备上配置的 Wi-Fi 网络相同）都与匹配的已配置 Wi-Fi 网络相同。因此，在迁移后，由自定义 DPC 配置的 Wi-Fi 网络不会受到影响，除非与该网络对应的 ONC 政策发生变化。不过，如果在迁移后卸载自定义 DPC，则由自定义 DPC 配置的 Wi-Fi 网络会自动移除。Android 设备政策会继续强制执行政策，并且如果政策中配置了任何这些网络，则会照常添加政策中配置的网络。

个人设备上的工作资料

出于技术原因，自定义设备政策控制器配置的 Wi-Fi 网络需要由自定义设备政策控制器移除，Android Device Policy 才能开始管理这些 Wi-Fi 网络。AMAPI SDK 会负责处理此问题，并在将所有权从自定义设备政策控制器 (DPC) 转移到 Android Device Policy 之前移除此类 Wi-Fi 网络，但它要求自定义设备政策控制器 (DPC) 在 DpcMigrationRequest 中传递有关这些网络的信息。迁移后，在政策中配置的网络将正常添加，因此建议在政策中配置自定义 DPC 添加的网络。

请注意以下几点：

  • 如果有效网络是由自定义 DPC 配置的 Wi-Fi 网络，则设备在迁移期间可能会短暂离线。
  • 只有自定义 DPC 配置的 Wi-Fi 网络应在 DpcMigrationRequest 中传递，否则如果 AMAPI SDK 无法移除某个网络（例如用户添加的 Wi-Fi 网络），迁移就会失败。
  • 只有当自定义 DPC 是个人所有设备上的资料所有者时，才应在 DpcMigrationRequest 中传递 WLAN 网络，否则迁移会失败。
  • 出于技术原因，Android 12 是一种特殊情况，其中会忽略在 DpcMigrationRequest 中传递的网络，并自动移除自定义设备政策控制器配置的所有 Wi-Fi 网络。此外，对于个人所有设备上的工作资料，自定义 DPC 必须在 Android 12 上拥有 ACCESS_WIFI_STATE 权限，否则迁移会失败。

注意事项

以下是与此功能相关的一些注意事项。

企业专属 ID

对于 Android 12 及更高版本上的工作资料，可从 DevicePolicyManager.getEnrollmentSpecificId 访问的企业专用 ID 在迁移时不会发生变化。不过，如果设备上再次创建由 Android Device Policy 管理的工作资料（例如在删除之前的工作资料或将设备恢复出厂设置后），企业专用 ID 会在此时发生变化。

完全托管设备中的工作资料

如果全托管式设备的工作资料运行的是 Android 9 或 10，则不支持此功能。不得尝试迁移这些设备，并且无论是否引发错误，这些设备都不支持 DPC 迁移。

RESET_PASSWORD 命令

如果设备设置了锁屏密码，则只有在迁移后用户确认其凭据（例如重新输入 PIN 码）后，RESET_PASSWORD 命令才会成功。如果设备没有锁屏密码，则可以在迁移后立即使用 RESET_PASSWORD 命令。