将现有设备迁移到 AMAPI

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

注意：此过程对最终用户是透明的。此过程是单向的（一旦完成便无法撤消），并且不能用于将设备从一个 EMM 迁移到另一个 EMM。

前提条件

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

在自定义 DPC 中与 AMAPI SDK 集成

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

注意：此过程需要使用 AMAPI SDK 库 1.1.4 版或更高版本。

迁移设备的步骤

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 functiong 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 返回的方法，也可以使用 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() {
    // 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 会继续强制执行政策，如果政策中配置了这些网络中的任何网络，则政策中配置的网络会照常添加。

个人设备上的工作资料

由于技术原因，Android Device Policy 的自定义 DPC 移除由自定义 DPC 配置的 Wi-Fi 网络才能开始管理这些 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 中传递 Wi-Fi 网络，否则迁移会失败。
• 由于技术原因，Android 12 是一个特殊情况，其中 DpcMigrationRequest 中传递的网络会被忽略，并且自定义 DPC 配置的所有 Wi-Fi 网络都会被自动移除。此外，自定义 DPC 必须在 Android 12 上对个人拥有的设备上的工作资料拥有 ACCESS_WIFI_STATE 权限，否则迁移会失败。

注意事项

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

企业专用 ID

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

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

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