将现有设备迁移到 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 已在设备上强制执行的政策。
  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 转移到 Android Device Policy 之前完成需要网络连接的关键操作。

迁移令牌

EMM 服务器会请求迁移令牌,以表明用户有意迁移由自定义 DPC 管理的特定设备。在迁移成功完成或过期之前,可以使用迁移令牌。

自定义 DPC 集成

首先,您需要创建一个 DpcMigrationRequest,并将令牌和已配置的 Wi-Fi 网络列表(如有必要)传递给其构建器:

// 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
}

跟踪迁移的进度

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

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

// 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() {
    // 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 网络与设备上配置的 Wi-Fi 网络具有相同的 SSID 和安全类型,并且与匹配的已配置 Wi-Fi 网络完全相同。因此,由自定义 DPC 配置的 Wi-Fi 网络在迁移后将保持不变,直到与该网络对应的 ONC 政策发生更改为止。不过,如果在迁移后卸载自定义 DPC,则系统会自动移除自定义 DPC 配置的 Wi-Fi 网络。Android Device Policy 会继续强制执行政策,如果其中任何网络已在政策中配置,系统会照常添加政策中配置的网络。

个人设备上的工作资料

由于技术原因,自定义 DPC 配置的 Wi-Fi 网络需要由适用于 Android Device Policy 的自定义 DPC 移除,才能开始管理这些 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 是个人自有设备上的资料所有者时,Wi-Fi 网络才应在 DpcMigrationRequest 中传递,否则迁移会失败。
  • 由于技术原因,Android 12 属于例外情况:在 DpcMigrationRequest 中传递的网络会被忽略,并且由自定义 DPC 配置的所有 Wi-Fi 网络都会被自动移除。此外,自定义 DPC 还要求在 Android 12 上对个人设备上的工作资料拥有 ACCESS_WIFI_STATE 权限,否则迁移将失败。

注意事项

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

企业专用 ID

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

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

如果全托管式设备拥有运行 Android 9 或 10 的工作资料,并不支持此功能。请勿尝试迁移这些设备,无论是否会发生错误,这类设备都不支持进行 DPC 迁移。