在新设备上设置时恢复应用凭据

Credential Manager 的恢复凭据功能允许用户在新设备上设置时恢复其应用帐号。此 API 处于开发者预览阶段,可在搭载 Android 9 或更高版本且 Google Play 服务 (GMS) Core 版本为 242200000 或更高版本的所有设备上使用。“恢复凭据”功能具有以下优势:

  • 流畅的用户体验:用户无需手动登录每个应用,即可恢复其应用帐号。
  • 提高用户活跃度:如果用户在新设备上设置时可以恢复其帐号,他们更有可能继续使用您的应用。
  • 减少开发工作量:“恢复凭据”功能已集成到 Credential Manager 中,因此已支持通行密钥的开发者可以添加凭据恢复功能。

工作原理

您可以使用“恢复凭据”来创建、获取和清除相关凭据。

  1. 创建恢复凭据:当用户登录您的应用时,创建一个与其帐号关联的恢复凭据。如果用户已启用 Google 备份且端到端加密可用,则此凭据将存储在本地并同步到云端(应用可以选择退出同步到云端)。
  2. 获取恢复凭据:当用户设置新设备时,您的应用可以从 Credential Manager 请求恢复凭据。这使您无需任何额外输入即可自动登录用户。
  3. 清除恢复凭据:当用户退出您的应用时,您应删除关联的恢复凭据。

“恢复凭据”功能可以与已实现通行密钥的后端系统顺畅集成。这种兼容性源于通行密钥和恢复密钥(“恢复凭据”功能使用的凭据类型)都遵循相同的底层技术规范。这种一致性确保了“恢复凭据”过程能够有效地检索和恢复存储在支持通行密钥的系统中的用户凭据,从而在不同的平台和身份验证方法之间提供一致且用户友好的体验。

Credential Manager bottom sheet
图 1. 演示使用恢复凭据将应用数据恢复到新设备的示意图,包括创建凭据、启动恢复流程和自动用户登录

实现

通过 Credential Manager Jetpack 库可以使用“恢复凭据”API。要开始使用,请按照以下步骤操作:

  1. 将 Credential Manager 依赖项添加到您的项目。

    // 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 部分。这样可确保在恢复应用数据后立即恢复应用的凭据。