Loja de blocos

Observação:para uma experiência do usuário atualizada e outras melhorias, use chaves de acesso com o Gerenciador de credenciais .

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

A API Block Store permite que o app armazene dados que podem ser recuperados posteriormente para autenticar novamente os usuários em um novo dispositivo. Isso ajuda a fornecer 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:

• Solução criptografada de armazenamento de credenciais para desenvolvedores. As credenciais são criptografadas de ponta a ponta sempre que possível.
• salvar tokens em vez de nomes de usuário e senhas;
• Eliminar o atrito dos fluxos de login.
• Evite que os usuários precisem gerenciar senhas complexas.
• O Google verifica a identidade do usuário.

Observação :o uso do Block Store não limita o usuário aos tipos de credenciais que podem ser utilizados. Os usuários podem fazer login com o nome de usuário e senha, a Conta do Google ou qualquer outro provedor de identidade federado, e a Block Store ainda funciona.

Antes de começar

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

Configurar o app

No arquivo build.gradle do 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.2.0'
}

Como funciona

O Block Store permite que os desenvolvedores salvem e restaurem matrizes de até 16 bytes. Isso permite que você salve informações importantes sobre a sessão atual do usuário e oferece flexibilidade para salvar essas informações como você quiser. Esses dados podem ser criptografados de ponta a ponta, e a infraestrutura de suporte da 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 funcionaria:

1. Durante o fluxo de autenticação do app ou a qualquer momento posteriormente, você pode armazenar o token de autenticação do usuário no Block Store para recuperação posterior.
2. O token será armazenado localmente e também poderá ser salvo em backup na nuvem, com criptografia 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, o app poderá recuperar o token salvo da Block Store no novo dispositivo.

Salvar o token

Quando um usuário faz login no seu app, você pode salvar o token de autenticação gerado para ele na Block Store. Você pode armazenar esse token usando um valor de par de chaves exclusivo que tenha, no máximo, 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 o Block Store, ele é criptografado e armazenado localmente no dispositivo.

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

Java

  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));

Kotlin

  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)
    }

Bytes armazenados anteriormente sem uma chave?

Se você já usou a API StoreBytes() para salvar seus dados, é recomendável começar a salvar os tokens com uma chave. Os dados salvos anteriormente com StoreBytes agora são salvos com a chave BlockstoreClient.DEFAULT_BYTES_DATA_KEY.

Usar token padrão

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

Java

  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));

Kotlin

  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 os dados são armazenados no dispositivo e quem pode acessá-los?

No dispositivo, os dados da BlockStore são armazenados no diretório de dados particulares local do Google Play Services. Nenhum outro app pode acessar diretamente o arquivo de dados. Eles só podem acessar os dados da BlockStore pela API retrieveBytes(), e um app só pode recuperar dados armazenados por conta própria. O Google Play Services verifica o nome e a assinatura do pacote.

Como recuperar o token

Mais tarde, quando um usuário passa pelo fluxo de restauração em um novo dispositivo, o Google Play Services primeiro verifica o usuário e, em seguida, recupera os dados do Block Store. O usuário já concordou em restaurar os dados do app como parte do fluxo de restauração, então nenhum consentimento adicional é necessário. Quando o usuário abrir o app, você poderá solicitar seu token da Block Store chamando retrieveBytes(). O token recuperado pode ser usado para manter o usuário conectado no novo dispositivo.

Veja na amostra a seguir como recuperar vários tokens com base em chaves específicas.

Java

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 blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry 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));

Kotlin

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)
  }

Recuperação de todos os tokens

Veja abaixo um exemplo de como recuperar todos os tokens salvos no BlockStore.

Java

BlockstoreClient client = Blockstore.getClient(this)

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

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry 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));

Kotlin

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)
  }

Descontinuação de recoveryBytes().

O retrieveBytes() foi descontinuado. Para recuperar bytes, a chave BlockstoreClient.DEFAULT_BYTES_DATA_KEY pode ser usada na instância RetrieveBytesRequest para acessar os dados salvos

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

Java

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

Kotlin

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 do BlockStore pode ser necessária pelos seguintes motivos:

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

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

Confira abaixo um exemplo da exclusão de determinadas chaves.

Java

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)

Kotlin

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 abaixo exclui todos os tokens salvos no BlockStore:

Java

// 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));

Kotlin

  val deleteAllRequest = DeleteBytesRequest.Builder()
  .setDeleteAll(true)
  .build()
client.deleteBytes(deleteAllRequest)
  .addOnSuccessListener { result: Boolean ->
    Log.d(TAG,
          "Any data found and deleted? $result")
  }

Criptografia de ponta a ponta

Para que a criptografia de ponta a ponta seja disponibilizada, o dispositivo precisa executar o Android 9 ou versão mais recente, e o usuário precisa ter definido um bloqueio de tela (PIN, padrão ou senha) para o dispositivo. Para verificar se a criptografia estará disponível no dispositivo, chame isEndToEndEncryptionAvailable().

O exemplo a seguir mostra como verificar se a criptografia estará disponível durante o backup na nuvem:

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

Observação :é recomendado verificar se a criptografia de ponta a ponta está disponível antes de ativar o backup na nuvem.

Ative o backup na nuvem

Para ativar o backup na nuvem, adicione o método setShouldBackupToCloud() ao objeto StoreBytesData. O Block Store fará o backup periódico dos bytes armazenados na nuvem quando setShouldBackupToCloud() for definido como verdadeiro.

O exemplo a seguir mostra como ativar o backup na nuvem somente quando ele é 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.")
          }
        }

Observação :se storeBytes for chamado com shouldBackupToCloud não definido ou definido como false, os bytes do dispositivo salvos em backup anteriormente na nuvem serão excluídos da nuvem na próxima sincronização periódica.

Como testar

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

Desinstale/reinstalação do mesmo dispositivo

Se o usuário ativar os serviços de backup (confira essa opção em Configurações > Google > Backup), os dados do Block Store serão persistentes durante a desinstalação/reinstalação do app.

Siga estas etapas para testar:

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

Observação: como é preciso mais etapas para testar a restauração em dispositivos diferentes, é recomendável verificar primeiro a integração do app com a API BlockStore usando o caso de desinstalação/reinstalação.

Dispositivo para dispositivo

Na maioria dos casos, isso exige a redefinição do dispositivo de destino para a configuração original. Depois, você pode entrar no fluxo de restauração sem fio do Android ou na restauração de cabos do Google (para dispositivos com suporte).

Observação: se o dispositivo de destino for um Samsung Galaxy, você poderá entrar no fluxo de restauração iniciando o Smart Switch fora da configuração.

Restauração na nuvem

1. Integre a API Blockstore ao app de teste. O app de teste precisa ser enviado à Play Store.
2. No dispositivo de origem, use o app de teste para invocar a API Blockstore e armazenar seus dados, com shouldBackUpToCloud definido como verdadeiro.
3. Para dispositivos O e mais recentes, é possível 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 concluído, faça o seguinte:
      1. Depois que o backup for concluído, procure linhas de registro com a tag "CloudSyncBpTkSvc".
      2. Você verá linhas como estas: “......, CloudSyncBpTkSvc: sync result: SUCCESS, ..., upload size: XXX bytes ..."
   2. Após um backup na nuvem da Block Store, há um período de espera de cinco minutos. Em cinco minutos, clicar no botão "Fazer backup agora" não acionará outro backup na nuvem da Block Store.
4. Redefina o dispositivo de destino para a configuração original e realize o fluxo de restauração da nuvem. Selecione para restaurar o app de teste durante o fluxo de restauração. Para mais informações sobre fluxos de restauração para a nuvem, consulte Fluxos de restauração de nuvem compatíveis.
5. No dispositivo de destino, use o app de teste para invocar a API Blockstore e recuperar seus dados.
6. Verifique se os bytes recuperados são iguais aos armazenados no dispositivo de origem.

Requisitos do dispositivo

Criptografia de ponta a ponta

• A criptografia de ponta a ponta pode ser usada em dispositivos com o Android 9 (nível 29 da API) e versões mais recentes.
• O dispositivo precisa ter um bloqueio de tela definido com um PIN, um padrão ou uma senha para que a criptografia de ponta a ponta seja ativada e os dados do usuário sejam criptografados corretamente.

Observação: isEndtoEndEncryptionAvailable() vai retornar "false" se alguma dessas condições não for atendida.

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 de destino. Esses serão os dois dispositivos que estão transferindo dados.

Os dispositivos de origem precisam ter o Android 6 (nível 23 da API) ou mais recente para fazer backup.

Target: dispositivos com o Android 9 (nível 29 da API) e versões mais recentes para poder fazer a restauração.

Você pode encontrar mais informações sobre o fluxo de restauração de dispositivo para dispositivo neste link.

Fluxo de backup e restauração na nuvem

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

Os dispositivos de origem precisam ter o Android 6 (nível 23 da API) ou mais recente para fazer backup.

Os dispositivos de segmentação são compatíveis com base nos fornecedores. Dispositivos Pixel podem usar esse recurso a partir do Android 9 (nível 29 da API), e todos os outros dispositivos precisam ter o Android 12 (nível 31 da API) ou mais recente.