Restaurar credenciais

O recurso Restaurar credenciais do Gerenciador de credenciais permite que os usuários restaurem as contas do app ao configurar um novo dispositivo. Essa API está na prévia para desenvolvedores e está disponível em todos os dispositivos que tenham o Android 9 ou mais recente e a versão 242200000 ou mais recente do núcleo dos serviços do Google Play (GMS, na sigla em inglês). Os benefícios do recurso "Restaurar credenciais" incluem:

• Experiência do usuário integrada: os usuários podem restaurar a conta do app sem precisar fazer login manualmente em cada app.
• Aumento do engajamento do usuário: os usuários vão continuar usando seu app com mais frequência se puderem restaurar a conta ao configurar um novo dispositivo.
• Menor esforço de desenvolvimento: o recurso "Restaurar credenciais" é integrado ao Gerenciador de credenciais. Assim, os desenvolvedores que já oferecem suporte a chaves de acesso podem adicionar recursos de restauração de credenciais.

Como funciona

É possível usar a opção "Restaurar credenciais" para criar, receber e limpar as credenciais relevantes.

1. Criar a credencial de restauração: quando o usuário fizer login no app, crie uma credencial de restauração associada à conta dele. Essa credencial é armazenada localmente e sincronizada com a nuvem se o usuário tiver ativado o Backup do Google e a criptografia de ponta a ponta estiver disponível (os apps podem desativar a sincronização com a nuvem).
2. Recuperar a credencial: quando o usuário configura um novo dispositivo, o app pode solicitar a recuperação da credencial ao Gerenciador de credenciais. Isso permite que você faça o login do usuário automaticamente sem precisar de nenhuma entrada extra.
3. Limpar a credencial de restauração: quando o usuário sair do app, exclua a credencial de restauração associada.

O recurso "Restaurar credenciais" pode ser integrado sem problemas a sistemas de back-end que já implementaram chaves de acesso. Essa compatibilidade ocorre porque as chaves de acesso e as chaves de restauração (tipo de credencial usada pelo recurso de restauração de credenciais) seguem as mesmas especificações técnicas subjacentes. Esse alinhamento garante que o processo de restauração de credenciais possa recuperar e restabelecer de forma eficaz as credenciais do usuário armazenadas em sistemas com chave de acesso, oferecendo uma experiência consistente e fácil de usar em diferentes plataformas e métodos de autenticação.

Figura 1. Diagrama que mostra a restauração de dados de um app em um novo dispositivo usando uma credencial de restauração, incluindo a criação da credencial, a inicialização de um fluxo de restauração e o login automático do usuário

Observação: as chaves de restauração são o único tipo de credencial compatível com esse recurso. Outros tipos de credenciais, como senhas, tokens de segurança ou dados biométricos, não são compatíveis.

Implementação

A API Restore Credentials está disponível na biblioteca do Jetpack do Gerenciador de credenciais. Para começar, siga estas etapas:

1. Adicione a dependência do Gerenciador de credenciais ao seu projeto.

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

2. Crie um objeto CreateRestoreCredentialRequest.

   Observação: defina a flag isCloudBackupEnabled como true para ativar o backup automático do restoreKey (se o usuário tiver ativado o Backup do Google e a criptografia de ponta a ponta estiver disponível). Defina-o como false se quiser que o restoreKey seja armazenado localmente e não na nuvem.

3. Chame o método createCredential() no objeto CredentialManager.

   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)
   

   Essa credencial de restauração gerada é um tipo de chave de acesso e também é conhecida como chave de acesso de restauração ou chave de restauração.

4. Quando o usuário configura um novo dispositivo, chame o método getCredential() no objeto CredentialManager.

   // 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. Quando o usuário sair do app, chame o método clearCredentialState() no objeto CredentialManager.

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

Se você estiver usando um agente de backup, execute a parte getCredential no callback onRestore. Isso garante que as credenciais do app sejam restauradas imediatamente após a restauração dos dados do app.

Observação: a restauração de credenciais não processa o cenário em que um app é reinstalado no mesmo dispositivo. A desinstalação de um app é interpretada como uma intent para excluir a chave de restauração correspondente desse dispositivo.