This skill guides the migration of local key-value storage from iOS
(UserDefaults and @AppStorage) to Android (Preferences DataStore and
SharedPreferences). You Must use this skill when porting apps that rely on
persistent user settings, flags, or small amounts of data storage.
Official Reference Links:
- DataStore overview | Android Developers
- SharedPreferences | Android Developers
- Data and files security best practices | Android Developers
Prerequisites
Before initiating the preferences migration, you Must ensure the following prerequisites are met:
- Source Context: Access to the iOS codebase using
UserDefaultsor@AppStorageis Mandatory. - Software Requirements: Android Gradle Plugin (AGP) 8.0+, Kotlin 1.8+,
Kotlin Coroutines (
kotlinx-coroutines-android:1.7+), and Jetpack DataStore (androidx.datastore:datastore-preferences:1.1+) are Mandatory. - Jetpack Compose: Understanding of state management in Compose (e.g.,
collectAsState) is Mandatory for mapping@AppStorage.
Limitations
This skill has the following limitations:
- Complex Objects: Storing complex custom objects in
UserDefaultsviaCodableshould be migrated to Proto DataStore or Room. This skill provides a foundational implementation for Proto DataStore; advanced topics like schema evolution or custom data migrations are outside its scope. - Secure Storage: This skill focuses on non-secure preferences. For sensitive data like passwords or tokens, refer to the Keychain to encrypted DataStore (Tink) mapping section. Evaluate the need for a dedicated biometrics skill if the flow requires user authentication to access the secure data.
Glossary
| iOS Concept | Android Equivalent | Definition |
|---|---|---|
| UserDefaults | Preferences DataStore / SharedPreferences | The standard interface for storing small key-value pairs persistently. |
| @AppStorage | DataStore Flow + collectAsState | SwiftUI property wrapper that reflects UserDefaults values and invalidates view. |
| Codable (to UserDefaults) | Proto DataStore / Room | Mechanism for serializing objects for storage. |
| Keychain | DataStore + Tink (Android Keystore-backed key) | Secure storage for sensitive data. |
Data Types Mapping
You Must map iOS data types to the correct Android DataStore preference keys.
| iOS Type | Android DataStore Key Type | Example |
|---|---|---|
Bool |
booleanPreferencesKey |
booleanPreferencesKey("is_logged_in") |
String |
stringPreferencesKey |
stringPreferencesKey("username") |
Int |
intPreferencesKey |
intPreferencesKey("visit_count") |
Float |
floatPreferencesKey |
floatPreferencesKey("score") |
Double |
doublePreferencesKey |
doublePreferencesKey("latitude") |
Array<String> |
stringSetPreferencesKey |
stringSetPreferencesKey("tags") |
Setup & Dependencies
You Must add the DataStore dependency (and Tink, if the app stores secrets)
to your app/build.gradle.kts file using Version Catalogs.
Example: libs.versions.toml ```toml [versions] datastore = "1.0.0" tink = "1.24.0"
[libraries] datastore-preferences = { group = "androidx.datastore", name = "datastore-preferences", version.ref = "datastore" } tink-android = { group = "com.google.crypto.tink", name = "tink-android", version.ref = "tink" } ```
Example: app/build.gradle.kts
kotlin
dependencies {
implementation(libs.datastore.preferences)
implementation(libs.tink.android)
}
Instructions: UserDefaults to DataStore
DataStore is the modern, recommended replacement for SharedPreferences. It
handles data updates transactionally and exposes data as a Flow.
Step 1: Creating the DataStore Instance
You Must create the DataStore instance at the top level of your file or use dependency injection.
- iOS:
UserDefaults.standard - Android:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")
Example: Initialization
- Input:
Context(via extension property). - Output:
DataStore<Preferences>instance. - Side Effect: Creates a file-backed data store named "user_preferences".
// At top level or in a singleton
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "user_preferences")
Step 2: Defining Keys
Android DataStore requires typed keys.
- iOS: Uses raw strings as keys.
- Android: You Must use
booleanPreferencesKey,stringPreferencesKey, etc.
Example: Defining Keys
- Input: String key names.
- Output: Typed
Preferences.Keyobjects. - Side Effect: None (pure definition).
object PreferencesKeys {
val IS_LOGGED_IN = booleanPreferencesKey("is_logged_in")
val USERNAME = stringPreferencesKey("username")
}
Step 3: Reading Data
DataStore exposes data via a Flow. You Must handle potential exceptions.
- iOS:
UserDefaults.standard.bool(forKey: "isLoggedIn") - Android:
dataStore.data.map { it[IS_LOGGED_IN] ?: false }
Example: Reading Data
- Input: None (reads from
dataStore). - Output:
Flow<Boolean>emitting current state. - Side Effect: Reads from disk asynchronously; handles IO exceptions.
val isLoggedInFlow: Flow<Boolean> = context.dataStore.data
.catch { exception ->
if (exception is IOException) {
emit(emptyPreferences())
} else {
throw exception
}
}
.map { preferences ->
preferences[PreferencesKeys.IS_LOGGED_IN] ?: false
}
Step 4: Writing Data
Writing to DataStore is asynchronous and requires a suspend function.
- iOS:
UserDefaults.standard.set(true, forKey: "isLoggedIn") - Android:
dataStore.edit { prefs -> prefs[IS_LOGGED_IN] = true }
Example: Writing Data
- Input:
Context,loggedIn(Boolean). - Output:
Unit(via suspend function). - Side Effect: Performs a transactional write to disk.
suspend fun setLoggedIn(context: Context, loggedIn: Boolean) {
context.dataStore.edit { preferences ->
preferences[PreferencesKeys.IS_LOGGED_IN] = loggedIn
}
}
Instructions: SwiftUI @AppStorage Mapping
SwiftUI's @AppStorage automatically updates the view when the underlying
UserDefaults value changes. In Android Compose, you Must collect the
DataStore Flow as state.
- iOS:
@AppStorage("username") var username = "Guest" - Android:
val username by dataStore.data.map { it[USERNAME] ?: "Guest" }.collectAsState(initial = "Guest")
Example: Compose Usage
- Input:
UserViewModelprovidingusernameFlow. - Output: Composable UI emitting
Text. - Side Effect: Recomposes when the DataStore flow emits new values.
@Composable
fun UserProfileScreen(viewModel: UserViewModel = viewModel()) {
val username by viewModel.usernameFlow.collectAsState(initial = "Guest")
// <string name="welcome_user">Welcome, %1$s</string>
Text(text = stringResource(R.string.welcome_user, username))
}
Instructions: Complex Objects (Proto DataStore)
If the iOS app stores complex objects in UserDefaults (e.g., via Codable),
you Must use Proto DataStore or Room on Android. Proto DataStore
allows you to store instances of a custom data type with a schema defined using
Protocol Buffers.
Example: Proto DataStore Implementation
- Define the Schema (
app/src/main/proto/user_prefs.proto): - Input: Proto schema definition.
- Output: Generated Java/Kotlin classes. ```proto syntax = "proto3";
option java_package = "com.example.application"; option java_multiple_files = true;
message UserPreferences { string username = 1; bool is_logged_in = 2; } ```
- Create the Serializer:
- Input:
InputStream. - Output:
UserPreferencesobject. ```kotlin object UserPreferencesSerializer : Serializer{ override val defaultValue: UserPreferences = UserPreferences.getDefaultInstance()
override suspend fun readFrom(input: InputStream): UserPreferences { try { return UserPreferences.parseFrom(input) } catch (exception: InvalidProtocolBufferException) { throw CorruptionException("Cannot read proto.", exception) } }
override suspend fun writeTo(t: UserPreferences, output: OutputStream) = t.writeTo(output) } ```
- Create DataStore Instance:
- Input: File name and serializer.
- Output:
DataStore<UserPreferences>instance.kotlin val Context.userPreferencesStore: DataStore<UserPreferences> by dataStore( fileName = "user_prefs.pb", serializer = UserPreferencesSerializer )
- When to use: When you have non-trivial data structures that don't require a full relational database like Room.
Instructions: Migrating SharedPreferences to DataStore
If you are migrating a legacy Android app that was previously ported from iOS
using SharedPreferences, you Must use SharedPreferencesMigration to move
data to DataStore without data loss.
Example: SharedPreferences Migration
- Input: Legacy SharedPreferences name ("legacy_prefs").
- Output:
DataStore<Preferences>instance with migration logic. - Side Effect: Migrates data from SharedPreferences to DataStore on first run.
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(
name = "user_preferences",
produceMigrations = { context ->
listOf(SharedPreferencesMigration(context, "legacy_prefs"))
}
)
Production Insight: DataStore vs SharedPreferences
While DataStore is the modern recommendation, many legacy production
applications actively being developed still heavily rely on SharedPreferences.
- iOS Real-World Implementation: Often uses extended native wrappers over
UserDefaultsconfigured via a centralizedSettings.swift. - Android Real-World Equivalent: The exact same centralized configuration
is observed via an interface
Settings.ktbacked by aSettingsImplclass injectingSharedPreferences.
Logic:
- IF the iOS application heavily wraps
UserDefaultssynchronously, THENSharedPreferencesremains the most direct 1:1 functional map, as DataStore requires migrating synchronous calls to reactive CoroutineFlowswhich can introduce significant architectural overhead during a 1:1 port. - ELSE, you Must use DataStore for all new development.
Instructions: Secure Storage (Keychain to encrypted DataStore)
For sensitive data like tokens, iOS uses Keychain. On Android, you Must encrypt the value with Tink using a key protected by the Android Keystore, and store the ciphertext in DataStore.
Logic:
- IF the iOS Keychain is used for simple key-value data (e.g., API
tokens), THEN you Must migrate it to DataStore, with each value
encrypted by a Tink
Aeadwhose keyset is protected by an Android Keystore master key. - IF the Keychain holds sign-in credentials (passwords, passkeys), THEN you Must prefer Credential Manager over storing them yourself.
- IF Keychain access is gated by biometrics or requires complex access control, THEN you Must evaluate the need for a dedicated security skill handling BiometricPrompt.
Example: Tink-encrypted DataStore value
- Input: Context, a DataStore, the secret to store.
- Output: An
Aeadthat encrypts and decrypts values; ciphertext stored in DataStore. - Side Effect: Creates an Android Keystore master key and an encrypted keyset in app-private storage on first use.
AeadConfig.register()
val aead: Aead = AndroidKeysetManager.Builder()
.withSharedPref(context, "secure_keyset", "secure_keyset_prefs")
.withKeyTemplate(KeyTemplates.get("AES256_GCM"))
.withMasterKeyUri("android-keystore://secure_master_key")
.build()
.keysetHandle
.getPrimitive(RegistryConfiguration.get(), Aead::class.java)
val TOKEN = stringPreferencesKey("auth_token")
val associatedData = "auth_token".encodeToByteArray()
suspend fun saveToken(token: String) {
val cipher = aead.encrypt(token.encodeToByteArray(), associatedData)
context.dataStore.edit {
it[TOKEN] = Base64.encodeToString(cipher, Base64.NO_WRAP)
}
}
val token: Flow<String?> = context.dataStore.data.map { prefs ->
prefs[TOKEN]?.let {
aead.decrypt(Base64.decode(it, Base64.NO_WRAP), associatedData)
.decodeToString()
}
}
Tooling Integration: Standard Actions
To enable automated assessment and migration tracking, this skill defines the following standard actions. Any automation tool built on this skill Must implement these actions with the specified parameters to ensure benchmark compliance.
Verification Commands & Agnostic Agent Instructions
To audit iOS preferences and verify DataStore migration:
- UserDefaults Scanner (CLI):
bash grep -rnE "UserDefaults\.standard|@AppStorage" . - DataStore Migration Verification:
Generate a Markdown verification checklist mapping each discovered iOS
UserDefaultskey to its KotlinDataStore<Preferences>/PreferencesKeycounterpart.
Antipatterns
DO
- DO use DataStore for all new non-secure preferences.
- DO encrypt sensitive data like auth tokens with Tink (Android Keystore-backed key) before storing it in DataStore.
- DO collect DataStore flows as state in Compose.
DON'T
- DON'T use the deprecated
EncryptedSharedPreferences/MasterKey(androidx.security:security-crypto). - DON'T use standard
SharedPreferencesfor new development unless migrating a legacy app with heavy synchronous dependencies. - DON'T store large amounts of data in preferences; use Room for complex data.
NEVER
- NEVER store raw passwords or sensitive tokens in plain
UserDefaultsorSharedPreferences. - NEVER perform blocking
first()orrunBlockingcalls on DataStore flows on the main thread.