設定新裝置時還原應用程式憑證

Credential Manager 的「Restore Credentials」功能可讓使用者在設定新裝置時還原應用程式帳戶。這個 API 目前處於開發人員預覽階段，適用於搭載 Android 9 以上版本，且 Google Play 服務 (GMS) Core 版本為 242200000 以上版本的所有裝置。還原憑證功能的優點包括：

  • 提供流暢的使用者體驗：使用者不必手動登入個別應用程式，即可還原應用程式帳戶。
  • 提高使用者參與度：如果使用者在設定新裝置時可以還原帳戶，就更有可能繼續使用您的應用程式。
  • 減少開發工作量：Restore Credentials 功能已與憑證管理工具整合，因此已支援密碼金鑰的開發人員可以新增憑證還原功能。

運作方式

您可以使用「還原憑證」功能建立、取得及清除相關憑證。

  1. 建立還原憑證：當使用者登入應用程式時，建立與其帳戶相關聯的還原憑證。如果使用者已啟用 Google 備份功能，且可使用端對端加密功能，則系統會將此憑證儲存在本機並同步至雲端 (應用程式可選擇不同步至雲端)
  2. 取得還原憑證：當使用者設定新裝置時，應用程式可以向憑證管理工具要求還原憑證。這樣一來，您就能自動登入使用者，不必再輸入任何其他內容。
  3. 清除還原憑證：當使用者登出應用程式時，您應刪除相關聯的還原憑證。

憑證還原功能可與已導入密碼金鑰的後端系統順利整合。這項相容性來自於密碼金鑰和還原金鑰 (「還原憑證」功能使用的憑證類型) 都遵循相同的基礎技術規格。這項對應功能可確保「還原憑證」程序能有效擷取及恢復儲存在支援密碼金鑰的系統中的使用者憑證，在不同平台和驗證方法之間提供一致且友善的使用者體驗。

Credential Manager 底部功能表
圖 1. 這張圖表說明如何使用還原憑證，將應用程式資料還原至新裝置，包括建立憑證、啟動還原流程，以及自動使用者登入作業

實作

您可以透過 Credential Manager Jetpack 程式庫使用 Restore Credentials API。首先，請按照下列步驟操作：

  1. 在專案中加入憑證管理工具依附元件。

    // build.gradle.kts
implementation("androidx.credentials:credentials:1.5.0-alpha03")

  2. 建立 CreateRestoreCredentialRequest 物件。

  3. 對 CredentialManager 物件呼叫 createCredential() 方法。

    val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

    系統產生的還原憑證是一種 WebAuthn 憑證，也稱為還原金鑰。

  4. 使用者設定新裝置時，請在 CredentialManager 物件上呼叫 getCredential() 方法。

    // Fetch the Authentication JSON from server
val authenticationJson = ...

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(Immutablelist.of(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

  5. 當使用者登出應用程式時，請在 CredentialManager 物件上呼叫 clearCredentialState() 方法。

    // Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)

如果您使用備份代理程式，請在 onRestore 回呼中執行 getCredential 部分。這可確保應用程式資料還原後，應用程式的憑證會立即還原。