Loja de blocos

Muitos usuários ainda gerenciam as próprias credenciais ao configurar um novo dispositivo Android. Esse processo manual pode ser desafiador e geralmente resulta em uma experiência insatisfatória para o usuário. A API Block Store, uma biblioteca com tecnologia do Google Play Services, busca resolver esse problema oferecendo uma maneira para os apps salvarem credenciais de usuário sem a complexidade ou o risco de segurança associado ao salvamento de senhas de usuários.

A API Block Store permite que seu app armazene dados que podem ser recuperados posteriormente para autenticar novamente os usuários em um novo dispositivo. Isso ajuda a proporcionar uma experiência mais integrada para o usuário, já que ele não precisa ver uma tela de login ao iniciar o app pela primeira vez no novo dispositivo.

Os benefícios de usar a Block Store incluem o seguinte:

• Solução de armazenamento de credenciais criptografadas para desenvolvedores. As credenciais são criptografadas de ponta a ponta quando possível.
• Salve tokens em vez de nomes de usuário e senhas.
• Elimine a dificuldade dos fluxos de login.
• Evite que os usuários tenham que gerenciar senhas complexas.
• O Google verifica a identidade do usuário.

Antes de começar

Para preparar o app, siga as etapas nas seções a seguir.

Configurar o app

No arquivo build.gradle para envolvidos no projeto, inclua o repositório Maven do Google nas seções buildscript e allprojects:

buildscript {
  repositories {
    google()
    mavenCentral()
  }
}

allprojects {
  repositories {
    google()
    mavenCentral()
  }
}

Adicione a dependência do Google Play Services para a API Block Store ao arquivo de build do Gradle do seu módulo, que geralmente é app/build.gradle:

dependencies {
  implementation 'com.google.android.gms:play-services-auth-blockstore:16.4.0'
}

Como funciona

A Block Store permite que os desenvolvedores salvem e restaurem até 16 matrizes de bytes. Isso permite salvar informações importantes sobre a sessão do usuário atual e oferece a flexibilidade de salvar essas informações da maneira que você quiser. Esses dados podem ser criptografados de ponta a ponta, e a infraestrutura que oferece suporte à Block Store é criada com base na infraestrutura de backup e restauração.

Este guia aborda o caso de uso de salvar o token de um usuário na Block Store. As etapas a seguir descrevem como um app que usa a Block Store funciona:

1. Durante o fluxo de autenticação do app ou a qualquer momento depois disso, você pode armazenar o token de autenticação do usuário na Block Store para recuperação posterior.
2. O token será armazenado localmente e também poderá ser feito backup na nuvem, criptografado de ponta a ponta quando possível.
3. Os dados são transferidos quando o usuário inicia um fluxo de restauração em um novo dispositivo.
4. Se o usuário restaurar o app durante o fluxo de restauração, ele poderá recuperar o token salvo da Block Store no novo dispositivo.

Como salvar o token

Quando um usuário faz login no seu app, você pode salvar o token de autenticação gerado para esse usuário na Block Store. É possível armazenar esse token usando um valor de par de chaves exclusivo que tem um máximo de 4 KB por entrada. Para armazenar o token, chame setBytes() e setKey() em uma instância de StoreBytesData.Builder para armazenar as credenciais do usuário no dispositivo de origem. Depois de salvar o token com a Block Store, ele será criptografado e armazenado localmente no dispositivo.

O exemplo a seguir mostra como salvar o token de autenticação no dispositivo local:

  BlockstoreClient client = Blockstore.getClient(this);
  byte[] bytes1 = new byte[] { 1, 2, 3, 4 };  // Store one data block.
  String key1 = "com.example.app.key1";
  StoreBytesData storeRequest1 = StoreBytesData.Builder()
          .setBytes(bytes1)
          // Call this method to set the key value pair the data should be associated with.
          .setKeys(Arrays.asList(key1))
          .build();
  client.storeBytes(storeRequest1)
    .addOnSuccessListener(result -> Log.d(TAG, "stored " + result + " bytes"))
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

  val client = Blockstore.getClient(this)

  val bytes1 = byteArrayOf(1, 2, 3, 4) // Store one data block.
  val key1 = "com.example.app.key1"
  val storeRequest1 = StoreBytesData.Builder()
    .setBytes(bytes1) // Call this method to set the key value with which the data should be associated with.
    .setKeys(Arrays.asList(key1))
    .build()
  client.storeBytes(storeRequest1)
    .addOnSuccessListener { result: Int ->
      Log.d(TAG,
            "Stored $result bytes")
    }
    .addOnFailureListener { e ->
      Log.e(TAG, "Failed to store bytes", e)
    }

Usar o token padrão

Os dados salvos usando StoreBytes sem uma chave usam a chave padrão BlockstoreClient.DEFAULT_BYTES_DATA_KEY.

  BlockstoreClient client = Blockstore.getClient(this);
  // The default key BlockstoreClient.DEFAULT_BYTES_DATA_KEY.
  byte[] bytes = new byte[] { 9, 10 };
  StoreBytesData storeRequest = StoreBytesData.Builder()
          .setBytes(bytes)
          .build();
  client.storeBytes(storeRequest)
    .addOnSuccessListener(result -> Log.d(TAG, "stored " + result + " bytes"))
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

  val client = Blockstore.getClient(this);
  // the default key BlockstoreClient.DEFAULT_BYTES_DATA_KEY.
  val bytes = byteArrayOf(1, 2, 3, 4)
  val storeRequest = StoreBytesData.Builder()
    .setBytes(bytes)
    .build();
  client.storeBytes(storeRequest)
    .addOnSuccessListener { result: Int ->
      Log.d(TAG,
            "stored $result bytes")
    }
    .addOnFailureListener { e ->
      Log.e(TAG, "Failed to store bytes", e)
    }

Como recuperar o token

Mais tarde, quando um usuário passar pelo fluxo de restauração em um novo dispositivo, o Google Play Services vai primeiro verificar o usuário e, em seguida, recuperar os dados da Block Store. O usuário já concordou em restaurar os dados do app como parte do fluxo de restauração. Portanto, não são necessários outros consentimentos. Quando o usuário abrir o app, você poderá solicitar seu token da Block Store chamando retrieveBytes(). O token recuperado poderá ser usado para manter o usuário conectado no novo dispositivo.

O exemplo a seguir mostra como recuperar vários tokens com base em chaves específicas.

BlockstoreClient client = Blockstore.getClient(this);

// Retrieve data associated with certain keys.
String key1 = "com.example.app.key1";
String key2 = "com.example.app.key2";
String key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY; // Used to retrieve data stored without a key

List requestedKeys = Arrays.asList(key1, key2, key3); // Add keys to array
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setKeys(requestedKeys)
    .build();

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map<String, BlockstoreData> blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry<String, BlockstoreData> entry : blockstoreDataMap.entrySet()) {
            Log.d(TAG, String.format(
                "Retrieved bytes %s associated with key %s.",
                new String(entry.getValue().getBytes()), entry.getKey()));
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

val client = Blockstore.getClient(this)

// Retrieve data associated with certain keys.
val key1 = "com.example.app.key1"
val key2 = "com.example.app.key2"
val key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY // Used to retrieve data stored without a key

val requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array

val retrieveRequest = RetrieveBytesRequest.Builder()
  .setKeys(requestedKeys)
  .build()

client.retrieveBytes(retrieveRequest)
  .addOnSuccessListener { result: RetrieveBytesResponse ->
    val blockstoreDataMap =
      result.blockstoreDataMap
    for ((key, value) in blockstoreDataMap) {
      Log.d(ContentValues.TAG, String.format(
        "Retrieved bytes %s associated with key %s.",
        String(value.bytes), key))
    }
  }
  .addOnFailureListener { e: Exception? ->
    Log.e(ContentValues.TAG,
          "Failed to store bytes",
          e)
  }

Como recuperar todos os tokens

Confira abaixo um exemplo de como recuperar todos os tokens salvos na BlockStore.

BlockstoreClient client = Blockstore.getClient(this)

// Retrieve all data.
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setRetrieveAll(true)
    .build();

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map<String, BlockstoreData> blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry<String, BlockstoreData> entry : blockstoreDataMap.entrySet()) {
            Log.d(TAG, String.format(
                "Retrieved bytes %s associated with key %s.",
                new String(entry.getValue().getBytes()), entry.getKey()));
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

val client = Blockstore.getClient(this)

val retrieveRequest = RetrieveBytesRequest.Builder()
  .setRetrieveAll(true)
  .build()

client.retrieveBytes(retrieveRequest)
  .addOnSuccessListener { result: RetrieveBytesResponse ->
    val blockstoreDataMap =
      result.blockstoreDataMap
    for ((key, value) in blockstoreDataMap) {
      Log.d(ContentValues.TAG, String.format(
        "Retrieved bytes %s associated with key %s.",
        String(value.bytes), key))
    }
  }
  .addOnFailureListener { e: Exception? ->
    Log.e(ContentValues.TAG,
          "Failed to store bytes",
          e)
  }

Confira abaixo um exemplo de como recuperar a chave padrão.

BlockStoreClient client = Blockstore.getClient(this);
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setKeys(Arrays.asList(BlockstoreClient.DEFAULT_BYTES_DATA_KEY))
    .build();
client.retrieveBytes(retrieveRequest);

val client = Blockstore.getClient(this)

val retrieveRequest = RetrieveBytesRequest.Builder()
  .setKeys(Arrays.asList(BlockstoreClient.DEFAULT_BYTES_DATA_KEY))
  .build()
client.retrieveBytes(retrieveRequest)

Como excluir tokens

A exclusão de tokens da BlockStore pode ser necessária pelos seguintes motivos:

• O usuário passa pelo fluxo de logout.
• O token foi revogado ou é inválido.

Assim como na recuperação de tokens, você pode especificar quais tokens precisam ser excluídos definindo uma matriz de chaves que exigem exclusão.

O exemplo a seguir demonstra como excluir determinadas chaves:

BlockstoreClient client = Blockstore.getClient(this);

// Delete data associated with certain keys.
String key1 = "com.example.app.key1";
String key2 = "com.example.app.key2";
String key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY; // Used to delete data stored without key

List requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array
DeleteBytesRequest deleteRequest = new DeleteBytesRequest.Builder()
      .setKeys(requestedKeys)
      .build();
client.deleteBytes(deleteRequest)

val client = Blockstore.getClient(this)

// Retrieve data associated with certain keys.
val key1 = "com.example.app.key1"
val key2 = "com.example.app.key2"
val key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY // Used to retrieve data stored without a key

val requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array

val retrieveRequest = DeleteBytesRequest.Builder()
      .setKeys(requestedKeys)
      .build()

client.deleteBytes(retrieveRequest)

Excluir todos os tokens

O exemplo a seguir mostra como excluir todos os tokens salvos na BlockStore:

// Delete all data.
DeleteBytesRequest deleteAllRequest = new DeleteBytesRequest.Builder()
      .setDeleteAll(true)
      .build();
client.deleteBytes(deleteAllRequest)
.addOnSuccessListener(result -> Log.d(TAG, "Any data found and deleted? " + result));

  val deleteAllRequest = DeleteBytesRequest.Builder()
  .setDeleteAll(true)
  .build()
retrieve bytes, the key BlockstoreClient.DEFAULT_BYTES_DATA_KEY can be used
in the RetrieveBytesRequest instance in order to get your saved data

The following example shows how to retrieve the default key.

End-to-end encryption

In order for end-to-end encryption to be made available, the device must be running Android 9 or higher, and the user must have set a screen lock (PIN, pattern, or password) for their device. You can verify if encryption will be available on the device by calling isEndToEndEncryptionAvailable().

The following sample shows how to verify if encryption will be available during cloud backup:

client.isEndToEndEncryptionAvailable()
        .addOnSuccessListener { result ->
          Log.d(TAG, "Will Block Store cloud backup be end-to-end encrypted? $result")
        }

Ativar o backup na nuvem

Para ativar o backup na nuvem, adicione o setShouldBackupToCloud() método ao seu StoreBytesData objeto. A Block Store fará backup periodicamente na nuvem dos bytes armazenados quando setShouldBackupToCloud() estiver definido como verdadeiro.

O exemplo a seguir mostra como ativar o backup na nuvem somente quando ele estiver criptografado de ponta a ponta:

val client = Blockstore.getClient(this)
val storeBytesDataBuilder = StoreBytesData.Builder()
        .setBytes(/* BYTE_ARRAY */)

client.isEndToEndEncryptionAvailable()
        .addOnSuccessListener { isE2EEAvailable ->
          if (isE2EEAvailable) {
            storeBytesDataBuilder.setShouldBackupToCloud(true)
            Log.d(TAG, "E2EE is available, enable backing up bytes to the cloud.")

            client.storeBytes(storeBytesDataBuilder.build())
                .addOnSuccessListener { result ->
                  Log.d(TAG, "stored: ${result.getBytesStored()}")
                }.addOnFailureListener { e ->
                  Log.e(TAG, “Failed to store bytes”, e)
                }
          } else {
            Log.d(TAG, "E2EE is not available, only store bytes for D2D restore.")
          }
        }

Como testar

Use os métodos a seguir durante o desenvolvimento para testar os fluxos de restauração.

Desinstalação/reinstalação no mesmo dispositivo

Se o usuário ativar os serviços de backup (que podem ser verificados em Configurações > Google > Backup), os dados da Block Store serão mantidos na desinstalação/reinstalação do app.

Siga estas etapas para testar:

1. Integre a API Block Store ao seu app de teste.
2. Use o app de teste para invocar a API Block Store para armazenar seus dados.
3. Desinstale o app de teste e reinstale-o no mesmo dispositivo.
4. Use o app de teste para invocar a API Block Store para recuperar seus dados.
5. Verifique se os bytes recuperados são os mesmos que foram armazenados antes da desinstalação.

De dispositivo para dispositivo

Na maioria dos casos, isso exigirá uma redefinição de fábrica do dispositivo de destino. Em seguida, você pode inserir o fluxo de restauração sem fio do Android ou a restauração por cabo do Google (para dispositivos compatíveis).

Restauração na nuvem

1. Integre a API Block Store ao seu app de teste. O app de teste precisa ser enviado à Google Play Store.
2. No dispositivo de origem, use o app de teste para invocar a API Block Store para armazenar seus dados, com shouldBackUpToCloud definido como true.
3. Para dispositivos com o Android O e versões mais recentes, você pode acionar manualmente um backup na nuvem da Block Store: acesse Configurações > Google > Backup e clique no botão "Fazer backup agora".
   1. Para verificar se o backup na nuvem da Block Store foi bem-sucedido, você pode:
      1. Depois que o backup terminar, pesquise linhas de registro com a tag "CloudSyncBpTkSvc".
      2. Você verá linhas como esta: "......, CloudSyncBpTkSvc: sync result: SUCCESS, ..., uploaded size: XXX bytes ..."
   2. Após um backup na nuvem da Block Store, há um período de "resfriamento" de 5 minutos. Dentro desses 5 minutos, clicar no botão "Fazer backup agora" não vai acionar outro backup na nuvem da Block Store.
4. Faça a redefinição de fábrica no dispositivo de destino e passe por um fluxo de restauração na nuvem. Selecione para restaurar o app de teste durante o fluxo de restauração. Para mais informações sobre fluxos de restauração na nuvem, consulte Fluxos de restauração na nuvem compatíveis.
5. No dispositivo de destino, use o app de teste para invocar a API Block Store para recuperar seus dados.
6. Verifique se os bytes recuperados são os mesmos que foram armazenados no dispositivo de origem.

Requisitos do dispositivo

Criptografia de ponta a ponta

• A criptografia de ponta a ponta é compatível com dispositivos que executam o Android 9 (API 29) e versões mais recentes.
• O dispositivo precisa ter um bloqueio de tela definido com um PIN, padrão ou senha para que a criptografia de ponta a ponta seja ativada e criptografe corretamente os dados do usuário.

Fluxo de restauração de dispositivo para dispositivo

A restauração de dispositivo para dispositivo exige que você tenha um dispositivo de origem e um dispositivo de destino. Esses serão os dois dispositivos que estão transferindo dados.

Os dispositivos de origem precisam executar o Android 6 (API 23) e versões mais recentes para fazer backup.

Os dispositivos de destino que executam o Android 9 (API 29) e versões mais recentes têm a capacidade de restaurar.

Mais informações sobre o fluxo de restauração de dispositivo para dispositivo podem ser encontradas aqui.

Fluxo de backup e restauração na nuvem

O backup e a restauração na nuvem exigem um dispositivo de origem e um dispositivo de destino.

Os dispositivos de origem precisam executar o Android 6 (API 23) e versões mais recentes para fazer backup.

Os dispositivos de destino são compatíveis com base nos fornecedores. Os dispositivos Pixel podem usar esse recurso no Android 9 (API 29), e todos os outros dispositivos precisam executar o Android 12 (API 31) ou versões mais recentes.