Sometimes it is necessary to migrate from native apps (e. g. iOS or Android) to a Flutter app. If there is already a user base, you do not want all users to lose their settings stored in the shared preferences once they update their app.
Let’s see why it’s not as simple as using the official SharedPreferences package to do the migration and what alternatives there are.
The first problem
How to store shared preferences in native apps
Shared preferences are (to the caller) nothing else but good old key-value-stores While Android reveals its underlying storage details to the developer, it is not that transparent on iOS. In fact, on Android, it is nothing else than a named XML file with the nodes having a name attribute and a value attribute.
On Android, if we do this:
1SharedPreferences sharedPrefs = context.getSharedPreferences(
2 "storage_name",
3 Context.MODE_PRIVATE
4);
5
6sharedPrefs.putString('key_name', 'value');
7editor.apply();
Choosing storage_name as the file name, key_name as the key, value as the value, it will result in this:
1/data/data/my.package/shared_prefs/storage_name.xml
So the package name determines the main directory, then there is a shared_prefs directory we are not able to alter and then there is the storage_name.xml whose name is determined by the first argument we put in the getSharedPreferences() method.
1<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
2<map>
3 <string name="key_name" value="value" />
4</map>
Now if we look at what is inside that file, we notice that there is a root node named map. In it, we find one child node with a tag name string which is derived from the type of method we called (in this case sharedPrefs.putString()). The two attributes name and value contain both of the arguments we provided.
How to read shared preferences in Flutter
Now how to we access this data within our Flutter app?
Using the official SharedPreferences package, we can simply do this:
We just create an instance of our SharedPreferences class and access the value knowing the type and key name by typing getString('key_name');. As simple as that.
No we are done, right? This is how we access the shared preferences previously stored on a native device, correct?
As you might have guessed, this would return null.
But why is that?
To understand what is happening, let us have a deeper look into the implementation of the plugin:
1class SharedPreferences {
2 SharedPreferences._(this._preferenceCache);
3
4 static const String _prefix = 'flutter.';
5 ...
6
7 Future<bool> _setValue(String valueType, String key, Object value) {
8 ArgumentError.checkNotNull(value, 'value');
9 final String prefixedKey = '$_prefix$key';
10 if (value is List<String>) {
11 // Make a copy of the list so that later mutations won't propagate
12 _preferenceCache[key] = value.toList();
13 } else {
14 _preferenceCache[key] = value;
15 }
16 return _store.setValue(valueType, prefixedKey, value);
17 }
18 ...
19}
In fact, we find a very strange _prefix variable in the shared_preferences.dart. And this exact _prefix is directly prepended to the key. The issue here is that it is defined as a const variable, which leaves us no choice to alter or omit this value.
So when we access key_name the way we tried, instead of looking for this:
1<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
2<map>
3 <string name="key_name" value="value" />
4</map>
The application actually looks for this:
1<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
2<map>
3 <string name="flutter.key_name" value="value" />
4</map>
You might ask yourself why the developers decided to do that. I can not answer this question. All I can say is that it makes the process of accessing shared preferences that have not been stored by this plugin but by any software that does not know anything about prefixes (like native apps) unnecessarily hard.
External package to the rescue
The Flutter community is very active and most problems are already solved by existing packages on pub.dev so this common problem must be addressed by any of them, right?
Yes, sort of.
There is a package called Native Shared Preferences which is basically a copy of the Shared Preferences package that omits this prefix. So you are free to prepend it yourself or not if you want to access natively stored data.
Does this fix our problem?
Yes, but only partly.
The second problem
As I have mentioned above, when storing data on Android, you are required to define a file name which determines the name of the XML file the preferences are stored in. Yet, we are not asked to define this file name when reading the value in the Flutter app. So which file does it look for?
In the Shared Preferences Package, the file name is (like the _prefix) statically defined with the arbitrary value FlutterSharedPreferences.
Again, I do not know why this is the way it was implemented. Even if the developers wanted to keep the Shared Preferences stored by Flutter separate from anything else, they could have at least made these predefined values only the default values but changeable nonetheless.
So instead of looking for this file:
1/data/data/my.package/shared_prefs/storage_name.xml
We can only read this file:
1/data/data/my.package/shared_prefs/FlutterSharedPreferences.xml
The Native Shared Preferences package has a solution for that. It says:
The issue is that flutter add a prefix to the keys when read and write. So we can not read our old keys. Also for Android you can now specify name of your resource file in
android/app/src/main/res/values/strings.xml
And this does indeed work. There is one problem, though. What if the Shared Preferences from my native app are spread across multiple XML files?
In fact, there is no solution for that. You can only choose one preferred file name.
If you only have a single XML file, you can stop right here, use the Native Shraed Preferences package and just define it like this:
1<resources>
2 ...
3 <string name="flutter_shared_pref_name">your_preferred_file_name</string>
4 ...
5</resources>
Where your_preferred_file_name is the name of your XML file and put this content into your android/app/src/main/res/values/strings.xml
The solution
If you have multiple XML files or you do not want to rely on this package, you have to go for a custom solution. This involves the usage of platform channel.
Android
Let’s start with the implementation of the Kotlin code:
1import android.content.*
2import androidx.annotation.NonNull
3import io.flutter.embedding.android.FlutterActivity
4import io.flutter.embedding.engine.FlutterEngine
5import io.flutter.plugin.common.MethodChannel
6
7class MainActivity: FlutterActivity() {
8 private val CHANNEL = "mypackage.com/shared_pref_migration"
9
10 override fun configureFlutterEngine(@NonNull flutterEngine: FlutterEngine) {
11 super.configureFlutterEngine(flutterEngine)
12 MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler {
13 call, result ->
14 when (call.method) {
15 "getStringValue" -> {
16 val key: String? = call.argument<String>("key");
17 val file: String? = call.argument<String>("file");
18
19 when {
20 key == null -> {
21 result.error("KEY_MISSING", "Argument 'key' is not provided.", null)
22 }
23 file == null -> {
24 result.error("FILE_MISSING", "Argument 'file' is not provided.", null)
25 }
26 else -> {
27 val value: String? = getStringValue(file, key)
28 result.success(value)
29 }
30 }
31 }
32 else -> {
33 result.notImplemented()
34 }
35 }
36 }
37 }
38
39 private fun getStringValue(file: String, key: String): String? {
40 return context.getSharedPreferences(
41 file,
42 Context.MODE_PRIVATE
43 ).getString(key, null);
44 }
45}
Basically, we use a when-statement (which is the Kotlin pendant to the switch statement you might know from other languages) to determine, which function to execute. In this case I only implemented the function for getting a String value. It is possible that the Shared Preferences XML file’s values have different data types, in which case you would have to implement separate functions for each case.
When the method property is equal to “getStringValue”, we read a String using the getString() method. We also read both of the arguments: key and file where key is the key of the value we have previously stored and file is the name of the XML file (which defaults to FlutterSharedPreferences in the Flutter context).
If one of the required arguments is not provided, we forward the error to the caller.
iOS
We continue by implementing the iOS part which requires us to write some Swift code:
1import UIKit
2import Foundation
3import Flutter
4
5@UIApplicationMain
6@objc class AppDelegate: FlutterAppDelegate {
7 override func application(
8 _ application: UIApplication,
9 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
10 ) -> Bool {
11 let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
12 let platformChannel = FlutterMethodChannel(
13 name: "mypackage.com/shared_pref_migration",
14 binaryMessenger: controller.binaryMessenger
15 )
16
17 platformChannel.setMethodCallHandler({
18 [weak self] (call: FlutterMethodCall, result: FlutterResult) -> Void in
19 guard call.method == "getStringValue" else {
20 result(FlutterMethodNotImplemented)
21 return
22 }
23
24 if let args: Dictionary<String, Any> = call.arguments as? Dictionary<String, Any>,
25 let number: String = args["key"] as? String, {
26 self?.getStringValue(key: key, result: result)
27 return
28 } else {
29 result(
30 FlutterError.init(
31 code: "KEY_MISSING",
32 message: "Argument 'key' is not provided.",
33 details: nil
34 )
35 )
36 }
37 })
38
39 GeneratedPluginRegistrant.register(with: self)
40 return super.application(application, didFinishLaunchingWithOptions: launchOptions)
41 }
42}
43
44private func getStringValue(key: String, result: FlutterResult) -> String? {
45 let fetchedValue: String? = UserDefaults.object(forKey: key) as? String
46 result(fetchedValue)
47}
It’s basically the same code in a different language and environment. There is one difference though: on iOS we are not required to specify a file name. That’s because the system does not forward details about the underlying storage mechanism to the caller. So we are left with the only relevant argument: the key.
Usage
How do we call the platform code now?
Let’s say we want to read the user id, a string that was previously stored within the native app context.
1import 'package:flutter/services.dart';
2
3 Future<String?> _getUserId() async {
4 try {
5 return await _getStringValue(_userIdKey, _userIdFile);
6 } on PlatformException catch (exception) {
7 print(exception);
8 return null;
9 }
10 }
11
12 Future<String?> _getStringValue(String key, String file) async {
13 final MethodChannel methodChannel = MethodChannel('mypackage.com/shared_pref_migration');
14 return methodChannel.invokeMethod('getStringValue', <String, dynamic>{
15 'key': key,
16 'file': file,
17 });
18 }
This is a simplified example as in the case of an error we just return null instead of properly handling it. But it should illustrate sufficiently how to call the platform channel.
The most important thing is that the channel name that is given to the constructor of the MethodChannel matches the channel name the native implementation listens to. Otherwise there will be no native code execution.
Conclusion
A rather common scenario – migrating shared preferences from native apps to Flutter apps – is surprisingly complicated. This is mainly man-made as it happens due to the fact that there are constant prefixes and file names involved. If the package owners of Shared Preferences just made these parts configurable, there would be no need to find a custom way around it.
However, the native implementation necessary to make it work is rather simple so the overall effort needed is acceptable.
yasmine kromel
Y
Marc
In reply to Y's comment