將現有裝置遷移至 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 網路的 SSID 和安全性類型 (即裝置上已設定的 Wi-Fi 網路) 與設定相符的 Wi-Fi 網路相同。因此,在遷移之後,自訂 DPC 設定的 Wi-Fi 網路會保持不變,直到與該網路相對應的 ONC 政策變更為止。不過,如果在遷移後解除安裝自訂 DPC,則自訂 DPC 設定的 Wi-Fi 網路會自動移除。Android Device Policy 會持續強制執行政策,如果政策中已設定這類網路,系統會照常新增政策中設定的網路。

個人裝置上的工作資料夾

基於技術因素,自訂 DPC 設定的 Wi-Fi 網路需由 Android Device Policy 的自訂 DPC 移除,才能開始管理這些 Wi-Fi 網路。AMAPI SDK 會負責這項工作並移除這類 Wi-Fi 網路,然後再將擁有權從自訂 DPC 轉移至 Android Device Policy,但前提是自訂 DPC 必須在 DpcMigrationRequest 中傳遞這些網路的相關資訊。遷移之後,系統會正常新增政策中設定的網路,因此建議同時在政策中設定由自訂 DPC 新增的網路。

請注意以下幾點:

  • 如果使用中的網路是自訂 DPC 設定的 Wi-Fi 網路,裝置可能會在遷移期間短暫離線。
  • 您只能在 DpcMigrationRequest 中傳遞自訂 DPC 設定的 Wi-Fi 網路,否則如果 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 或 Android 10 的工作資料夾,則不支援這項功能。請勿嘗試遷移這些裝置,不論是否發生錯誤,這些裝置都不支援執行 DPC 遷移作業。