將現有裝置遷移至 AMAPI

您可將已由自訂 DPC 管理的裝置遷移至 Android Device Policy (ADP)，並善用 Android Management API。

注意： 這項程序對使用者來說是透明的。這項程序只能單向執行 (完成後無法復原)，且無法用於將裝置從一個 EMM 遷移至另一個 EMM，或從一個企業遷移至另一個企業。

必要條件

• 裝置已由 EMM 透過自訂 DPC 管理。
• 自訂 DPC 已與 AMAPI SDK 整合。
• 裝置已透過 Google Play EMM API 註冊。
• 裝置屬於 Google Play 管理版帳戶企業。
• 裝置搭載 Android 9 以上版本。
• 如果是公司裝置上的工作資料夾，裝置必須搭載 Android 11 以上版本。

重要事項： 這個程序需要 AMAPI SDK 程式庫 1.1.4 以上版本。您可以在 AMAPI SDK 程式庫的版本資訊中，查看最新可用版本。強烈建議一律使用最新版本程式庫，以便享有可用的修正錯誤和改善項目。

在自訂 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。這個程序可用下列序列圖表示：

注意：裝置必須連上網際網路才能開始遷移。這項程序旨在確保遷移期間即使發生網路中斷，也不會影響遷移作業，因此系統會在實際轉移裝置擁有者或設定檔擁有者權限前，完成需要網路連線的重要作業。

遷移權杖

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。

重要事項： 這項功能需要導入 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 網路，只要與裝置上設定的 Wi-Fi 網路具有相同的 SSID 和安全性類型，就與相符的設定 Wi-Fi 網路相同。因此，在 ONC 政策中出現對應網路的變更之前，遷移後自訂 DPC 設定的 Wi-Fi 網路不會受到影響。不過，如果遷移後解除安裝自訂 DPC，系統會自動移除自訂 DPC 設定的 Wi-Fi 網路。Android 裝置政策會繼續強制執行政策，如果政策中設定了任何這類網路，系統會照常新增政策中設定的網路。

個人裝置上的工作資料夾

基於技術考量，自訂 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 是個人裝置上的設定檔擁有者時，才應傳遞 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 遷移作業都不支援這類裝置。

RESET_PASSWORD 指令

如果裝置設有螢幕鎖定密碼，使用者必須在遷移後確認憑證 (例如重新輸入 PIN 碼)，RESET_PASSWORD 指令才會成功。如果裝置沒有螢幕鎖定密碼，遷移作業完成後即可使用 RESET_PASSWORD 指令。