将现有设备迁移到 AMAPI

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

前提条件

在自定义 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 管理的特定设备的意图。迁移令牌可一直使用,直到迁移成功完成或令牌过期。

自定义 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
}

设置 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 Device Policy 会继续强制执行政策,如果政策中配置了任何此类网络,则系统会照常添加政策中配置的网络。

个人设备上的工作资料

出于技术原因,由自定义 DPC 配置的 Wi-Fi 网络需要由自定义 DPC 移除,以便 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 中传递的网络会被忽略,并且由自定义 DPC 配置的所有 Wi-Fi 网络都会自动移除。此外,在 Android 12 上,自定义 DPC 必须具有 ACCESS_WIFI_STATE 权限,才能在个人所有设备上使用工作资料,否则迁移会失败。

注意事项

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

企业特定 ID

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

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

搭载 Android 9 或 10 且设有工作资料的完全受管设备不支持此功能。不得尝试迁移这些设备,无论是否引发错误,此类设备都不支持 DPC 迁移。

RESET_PASSWORD 命令

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