SharedPreferences: ce este, depozitul cheie-valoare Android

Ce este SharedPreferences?

SharedPreferences este un mecanism încorporat Android pentru stocarea perechilor cheie-valoare într-un fișier XML pe memoria internă a dispozitivului. Este disponibil începând cu API Level 1 și nu necesită conectarea de biblioteci suplimentare. Scopul principal — salvarea setărilor utilizatorului, stării interfeței, flagurilor de first-launch și a altor date simple care nu necesită o bază de date structurată.

Fiecare fișier SharedPreferences este asociat cu un nume specific și un mod de acces. În mod implicit se utilizează modul Context.MODE_PRIVATE, care limitează accesul la fișier doar aplicației curente. Anterior Android suporta modurile MODE_WORLD_READABLE și MODE_WORLD_WRITEABLE, dar acestea au fost declarate învechite începând cu API Level 17 și complet eliminate în Android 7.0 (API 24) din motive de securitate.

În ciuda simplității sale, SharedPreferences este utilizat în milioane de aplicații Android. Potrivit Google, peste 90% din aplicațiile publicate pe Google Play folosesc SharedPreferences pentru stocarea setărilor. Cu toate acestea, pentru scenarii complexe (volume mari de date, siguranța tipurilor, asincronism) Google recomandă soluții mai moderne, cum ar fi Preferences DataStore din biblioteca Android Jetpack.

Formatul de stocare: XML pe dispozitiv

Fizic, SharedPreferences este stocat sub formă de fișier XML în directorul aplicației: /data/data/{package_name}/shared_prefs/{file_name}.xml. Fișierul conține elementul rădăcină <map> cu elemente copil <string>, <int>, <boolean>, <float> și <long> în funcție de tipul valorii salvate. Dimensiunea fișierului nu este limitată, dar pentru volume mari de date (peste 100 KB) performanța de citire și scriere începe să scadă considerabil.

Fișierele SharedPreferences nu sunt criptate implicit. Datele sunt stocate în formă deschisă în sistemul de fișiere al dispozitivului. Pentru stocarea datelor sensibile (tokeni, parole) se recomandă utilizarea EncryptedSharedPreferences din biblioteca AndroidX Security, care criptează automat cheile și valorile cu AES256-GCM.

Cum funcționează SharedPreferences în Android

SharedPreferences funcționează pe principiul stocării în cache cu sincronizare periodică pe disc. La prima accesare a fișierului (prin getSharedPreferences), Android încarcă fișierul XML în memoria RAM și îl parsează într-un obiect Map. Toate operațiile ulterioare de citire se execută din memorie, fără re-citire de pe disc. Aceasta asigură o viteză ridicată de acces la date.

Operațiile de scriere utilizează Editor — un buffer intern de modificări. Când dezvoltatorul apelează putString sau putBoolean, modificările sunt stocate în obiectul Editor în memorie. Scrierea efectivă pe disc are loc la apelarea metodei commit (sincron) sau apply (asincron). Până la apelarea acestor metode, datele nu sunt salvate, iar la terminarea forțată a aplicației modificările pot fi pierdute.

Moduri de acces și context

Pentru obținerea unei instanțe SharedPreferences se folosesc două metode: getPreferences și getSharedPreferences. Prima este disponibilă doar în interiorul Activity și creează un fișier cu numele Activity. A doua — mai flexibilă, acceptă numele fișierului și modul de acces, și este accesibilă din orice context (Application, Activity, Service). Se recomandă utilizarea getSharedPreferences cu un nume de fișier corespunzător modulului sau funcționalității aplicației.

// Obținerea SharedPreferences
val prefs = context.getSharedPreferences(
    "user_settings", Context.MODE_PRIVATE
)

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

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

La utilizarea MODE_MULTI_PROCESS (învechit) SharedPreferences se sincronizează între procese. Totuși, această sincronizare nu garantează atomicitatea, iar Google recomandă evitarea utilizării SharedPreferences în scenarii multi-process. Pentru astfel de cazuri, este mai bine să folosiți ContentProvider, Room cu acces inter-proces sau DataStore.

Metodele principale ale SharedPreferences

SharedPreferences oferă un set de metode pentru citirea datelor după cheie și interfața Editor pentru scriere. Fiecare metodă de citire acceptă doi parametri: cheia și valoarea implicită care este returnată dacă cheia nu este găsită. Valoarea implicită determină și tipul valorii returnate: getString returnează String, getInt — Int și așa mai departe.

Editor și apply vs commit

Editor — este obiectul intern al SharedPreferences care colectează modificările în buffer. După efectuarea tuturor modificărilor, dezvoltatorul apelează commit() (scriere sincronă) sau apply() (scriere asincronă). Diferența este critică: commit blochează firul de execuție curent până la scrierea completă pe disc și returnează boolean (succes/eșec), iar apply execută scrierea într-un fir de fundal și returnează imediat controlul, dar nu returnează rezultatul.

Se recomandă utilizarea apply în loc de commit în toate cazurile când nu este necesar să se cunoască rezultatul scrierii. apply este mai rapid și nu blochează firul UI. commit trebuie folosit doar când este crucial să se știe dacă datele au fost salvate cu succes sau la lucrul cu modul multi-process. Pentru ștergerea cheilor individuale se folosește metoda remove, pentru curățarea completă — clear. Toate operațiile de ștergere se execută de asemenea prin Editor.

// Modificări multiple - un singur apply
prefs.edit {
    putString("theme", "dark")
    putBoolean("notifications", false)
    remove("old_key")
}

// Ascultătorul modificării valorilor
prefs.registerOnSharedPreferenceChangeListener { prefs, key ->
    Log.d("TAG", "S-a modificat cheia: $key")
}

Începând cu Android 12 (API 31), SharedPreferences a fost completată cu suport pentru registerOnSharedPreferenceChangeListener cu dezabonare automată prin Lifecycle. Acest lucru permite evitarea scurgerilor de memorie asociate cu listeneri uitați. În versiunile mai vechi, dezvoltatorul este obligat să apeleze manual unregisterOnSharedPreferenceChangeListener în onDestroy sau onStop al componentei.

SharedPreferences vs alternative de stocare

În ciuda răspândirii largi, SharedPreferences nu este o soluție universală pentru toate scenariile de stocare a datelor în Android. În funcție de volumul datelor, cerințele de siguranță a tipurilor și performanță, Google recomandă diverse alternative incluse în Android Jetpack și biblioteca standard Android.

DataStore — alternativa modernă

DataStore — este o bibliotecă Android Jetpack, prezentată de Google ca înlocuitor pentru SharedPreferences. Oferă două variante: Preferences DataStore (cheie-valoare, ca SharedPreferences) și Proto DataStore (stocare tipizată prin Protocol Buffers). DataStore utilizează corutini și Flow pentru lucrul asincron, garantează siguranța tipurilor și gestionează automat migrările de versiuni. Google recomandă DataStore pentru toate proiectele noi.

Principalul avantaj al DataStore — asincronismul la nivel de API. Toate operațiile de citire returnează Flow, iar operațiile de scriere sunt funcții suspend. Acest lucru elimină complet blocarea firului UI, posibilă la citirea sincronă a SharedPreferences. În plus, DataStore garantează consistența datelor: scrierea se execută într-o tranzacție, iar în caz de avarie toate modificările sunt anulate.

Exemplu de utilizare SharedPreferences într-o aplicație

Să examinăm un exemplu practic: setările temei (deschis/închis/sistem) într-o aplicație Android. Utilizatorul alege tema, iar alegerea este salvată în SharedPreferences. La pornirile ulterioare ale aplicației, tema se restabilește din setările salvate. Pentru actualizarea reactivă a interfeței se utilizează observarea modificărilor prin SharedPreferences.OnSharedPreferenceChangeListener.

Salvarea setărilor utilizatorului

Vom crea clasa ThemePreferences, care încapsulează întreaga lucrare cu SharedPreferences pentru temă. Clasa oferă metodele getTheme (citire), setTheme (scriere) și observeTheme (observare). Numele fișierului de setări va fi „app_preferences" cu modul MODE_PRIVATE. Pentru comoditate, cheile sunt extrase în companion object ca constante.

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

În Activity sau Fragment, obținerea instanței ThemePreferences se realizează prin contextul aplicației. La inițializare se apelează getTheme pentru setarea temei curente. Când utilizatorul alege o temă nouă, se apelează setTheme, iar prin observeTheme interfața se actualizează fără repornirea Activity. Este important să nu uitați să vă dezabonați de la listener în onDestroy pentru a preveni scurgerile de memorie, mai ales dacă Activity este recreat la modificarea configurației.

Pentru aplicațiile cu versiunea țintă minimă Android 12+, se recomandă utilizarea registerOnSharedPreferenceChangeListener împreună cu LifecycleObserver. Acest lucru gestionează automat abonarea și dezabonarea la modificarea ciclului de viață al componentei. Pentru versiunile mai vechi, abonarea și dezabonarea trebuie gestionate manual, ceea ce este o sursă frecventă de erori în aplicațiile de producție care utilizează SharedPreferences.