SharedPreferences: o que é, armazenamento chave-valor do Android

O que é SharedPreferences?

SharedPreferences é um mecanismo integrado do Android para armazenar pares chave-valor em um arquivo XML no armazenamento interno do dispositivo. Está disponível desde a API Level 1 e não requer bibliotecas adicionais. Seu principal objetivo é salvar preferências do usuário, estado da interface, flags de primeiro lançamento e outros dados simples que não requerem um banco de dados estruturado.

Cada arquivo SharedPreferences está associado a um nome específico e modo de acesso. Por padrão, o modo Context.MODE_PRIVATE é usado, que restringe o acesso ao arquivo apenas ao aplicativo atual. Anteriormente, o Android suportava os modos MODE_WORLD_READABLE e MODE_WORLD_WRITEABLE, mas eles foram declarados obsoletos a partir da API Level 17 e completamente removidos no Android 7.0 (API 24) por razões de segurança.

Apesar de sua simplicidade, SharedPreferences é usado em milhões de aplicativos Android. De acordo com o Google, mais de 90% dos aplicativos publicados no Google Play usam SharedPreferences para armazenar configurações. No entanto, para cenários complexos (grandes volumes de dados, segurança de tipos, assincronia), o Google recomenda soluções mais modernas como o Preferences DataStore da biblioteca Android Jetpack.

Formato de armazenamento: XML no dispositivo

Fisicamente, SharedPreferences é armazenado como um arquivo XML no diretório do aplicativo: /data/data/{package_name}/shared_prefs/{file_name}.xml. O arquivo contém um elemento raiz <map> com elementos filhos <string>, <int>, <boolean>, <float> e <long> dependendo do tipo de valor armazenado. O tamanho do arquivo não é limitado, mas para grandes volumes de dados (mais de 100 KB), o desempenho de leitura e gravação começa a degradar significativamente.

Os arquivos SharedPreferences não são criptografados por padrão. Os dados são armazenados em texto simples no sistema de arquivos do dispositivo. Para armazenar dados sensíveis (tokens, senhas), recomenda-se usar EncryptedSharedPreferences da biblioteca AndroidX Security, que criptografa automaticamente chaves e valores usando AES256-GCM.

Como o SharedPreferences funciona no Android

SharedPreferences funciona com base no princípio de cache em memória com sincronização periódica em disco. No primeiro acesso ao arquivo (via getSharedPreferences), o Android carrega o arquivo XML na RAM e o analisa em um objeto Map. Todas as operações de leitura subsequentes são realizadas da memória, sem reler do disco. Isso garante alta velocidade de acesso aos dados.

As operações de gravação usam Editor — um buffer interno de alterações. Quando o desenvolvedor chama putString ou putBoolean, as alterações são armazenadas no objeto Editor na memória. A gravação real em disco ocorre quando o método commit (síncrono) ou apply (assíncrono) é chamado. Até que esses métodos sejam chamados, os dados não são salvos e, se o aplicativo falhar inesperadamente, as alterações podem ser perdidas.

Modos de acesso e contexto

Para obter uma instância de SharedPreferences, dois métodos são usados: getPreferences e getSharedPreferences. O primeiro está disponível apenas dentro de uma Activity e cria um arquivo com o nome da Activity. O segundo é mais flexível, aceita um nome de arquivo e modo de acesso, e está acessível a partir de qualquer contexto (Application, Activity, Service). Recomenda-se usar getSharedPreferences com um nome de arquivo correspondente ao módulo ou funcionalidade do aplicativo.

// Obtendo SharedPreferences
val prefs = context.getSharedPreferences(
    "user_settings", Context.MODE_PRIVATE
)

// Gravar dados
with(prefs.edit()) {
    putString("username", "Ana")
    putInt("age", 28)
    putBoolean("isLoggedIn", true)
    apply()
}

// Ler dados
val username = prefs.getString("username", "")
val age = prefs.getInt("age", 0)
val isLoggedIn = prefs.getBoolean("isLoggedIn", false)

Ao usar MODE_MULTI_PROCESS (obsoleto), o SharedPreferences sincroniza entre processos. No entanto, essa sincronização não garante atomicidade, e o Google recomenda evitar SharedPreferences em cenários multiprocesso. Para tais casos, é melhor usar ContentProvider, Room com acesso entre processos ou DataStore.

Métodos principais do SharedPreferences

SharedPreferences fornece um conjunto de métodos para ler dados por chave e a interface Editor para escrever. Cada método de leitura aceita dois parâmetros: uma chave e um valor padrão que é retornado se a chave não for encontrada. O valor padrão também determina o tipo de retorno: getString retorna String, getInt retorna Int, e assim por diante.

Editor e apply vs commit

Editor é um objeto interno do SharedPreferences que coleta alterações em um buffer. Após fazer todas as alterações, o desenvolvedor chama commit() (gravação síncrona) ou apply() (gravação assíncrona). A diferença é crítica: o commit bloqueia a thread atual até a gravação completa no disco e retorna um boolean (sucesso/fracasso), enquanto o apply realiza a gravação em uma thread em segundo plano e retorna o controle imediatamente, mas não retorna um resultado.

Recomenda-se usar apply em vez de commit em todos os casos em que não for necessário saber o resultado da gravação. apply é mais rápido e não bloqueia a thread da UI. O commit só deve ser usado quando é crítico saber se os dados foram salvos com sucesso, ou ao trabalhar com modo multiprocesso. Para remover chaves individuais, usa-se o método remove; para limpeza completa — clear. Todas as operações de exclusão também são realizadas através do Editor.

// Múltiplas alterações - um apply
prefs.edit {
    putString("theme", "dark")
    putBoolean("notifications", false)
    remove("old_key")
}

// Listener de mudança de valor
prefs.registerOnSharedPreferenceChangeListener { prefs, key ->
    Log.d("TAG", "Chave alterada: $key")
}

A partir do Android 12 (API 31), o SharedPreferences foi aprimorado com suporte para registerOnSharedPreferenceChangeListener com cancelamento automático de inscrição via Lifecycle. Isso ajuda a evitar vazamentos de memória associados a listeners esquecidos. Em versões mais antigas, o desenvolvedor deve chamar manualmente unregisterOnSharedPreferenceChangeListener no onDestroy ou onStop do componente.

SharedPreferences vs alternativas de armazenamento

Apesar de seu uso generalizado, SharedPreferences não é uma solução universal para todos os cenários de armazenamento de dados no Android. Dependendo do volume de dados, requisitos de segurança de tipos e desempenho, o Google recomenda várias alternativas incluídas no Android Jetpack e na biblioteca padrão do Android.

DataStore — alternativa moderna

DataStore é uma biblioteca do Android Jetpack apresentada pelo Google como substituta do SharedPreferences. Ela fornece duas variantes: Preferences DataStore (chave-valor, como SharedPreferences) e Proto DataStore (armazenamento tipado via Protocol Buffers). O DataStore usa corrotinas e Flow para operação assíncrona, garante segurança de tipos e lida automaticamente com migrações de versão. O Google recomenda DataStore para todos os novos projetos.

A principal vantagem do DataStore é a assincronia no nível da API. Todas as operações de leitura retornam Flow, e as operações de gravação são funções suspend. Isso elimina completamente o bloqueio da thread da UI que pode ocorrer com a leitura síncrona do SharedPreferences. Além disso, o DataStore garante a consistência dos dados: a gravação é realizada em uma transação e, em caso de falha, todas as alterações são revertidas.

Exemplo de uso do SharedPreferences em um aplicativo

Vamos considerar um exemplo prático: configurações de tema (claro/escuro/sistema) em um aplicativo Android. O usuário seleciona um tema e a escolha é salva em SharedPreferences. Em execuções posteriores do aplicativo, o tema é restaurado a partir das configurações salvas. Para atualizações reativas da interface, utiliza-se a observação de alterações através de SharedPreferences.OnSharedPreferenceChangeListener.

Salvando configurações do usuário

Vamos criar uma classe ThemePreferences que encapsula todo o trabalho com SharedPreferences para o tema. A classe fornece métodos getTheme (leitura), setTheme (gravação) e observeTheme (observação). O nome do arquivo de configurações será "app_preferences" com modo MODE_PRIVATE. Para conveniência, as chaves são colocadas em um objeto companion como constantes.

class ThemePreferences(context: Context) {
    companion object {
        private const val PREF_NAME = "app_preferences"
        private const val KEY_THEME = "theme_mode"
        const val THEME_LIGHT = "light"
        const val THEME_DARK = "dark"
        const val THEME_SYSTEM = "system"
    }

    private val prefs = context
        .getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)

    fun getTheme(): String =
        prefs.getString(KEY_THEME, THEME_SYSTEM) ?: THEME_SYSTEM

    fun setTheme(theme: String) {
        prefs.edit { putString(KEY_THEME, theme) }
    }

    fun observeTheme(callback: (String) -> Unit) {
        prefs.registerOnSharedPreferenceChangeListener { _, key ->
            if (key == KEY_THEME) {
                callback.invoke(getTheme())
            }
        }
    }
}

Em uma Activity ou Fragment, obter uma instância de ThemePreferences é feito através do contexto do aplicativo. Na inicialização, getTheme é chamado para definir o tema atual. Quando o usuário seleciona um novo tema, setTheme é chamado e, através de observeTheme, a interface é atualizada sem reiniciar a Activity. É importante cancelar a inscrição do listener no onDestroy para evitar vazamentos de memória, especialmente se a Activity for recriada ao alterar a configuração.

Para aplicativos com versão mínima alvo Android 12+, recomenda-se usar registerOnSharedPreferenceChangeListener juntamente com LifecycleObserver. Isso gerencia automaticamente a inscrição e o cancelamento ao alterar o ciclo de vida do componente. Para versões mais antigas, a inscrição e o cancelamento devem ser gerenciados manualmente, o que é uma fonte frequente de erros em aplicativos de produção que usam SharedPreferences.