[shared_preferences] Add information about shared preferences android to docs (flutter#8296)

Adds documentation for android shared preferences async shared preferences update.

Author: tarrinneal

packages/shared_preferences/shared_preferences/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.3.5
+
+* Adds information about Android SharedPreferences support.
+
 ## 2.3.4
 
 * Security update, requires shared_preferences_android to be 2.3.4.

packages/shared_preferences/shared_preferences/README.md

@@ -50,9 +50,25 @@ latest data stored on the native platform regardless of what process was used to
 
 ### Android platform storage
 
-The [SharedPreferences] API uses the native [Android Shared Preferences](https://developer.android.com/reference/android/content/SharedPreferences) tool to store data.
+The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs can use [DataStore Preferences](https://developer.android.com/topic/libraries/architecture/datastore) or [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) to store data.
+In most cases you should use the default option of DataStore Preferences, as it is the platform-recommended preferences storage system. 
+However, in some cases you may need to interact with preferences that were written to SharedPreferences by code you don't control.
 
-The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs use [DataStore Preferences](https://developer.android.com/topic/libraries/architecture/datastore) to store data.
+To use the `Android SharedPreferences` backend, use the `SharedPreferencesAsyncAndroidOptions` when using [SharedPreferencesAsync] on Android.
+<?code-excerpt "readme_excerpts.dart (Android_Options1)"?>
+```dart
+import 'package:shared_preferences_android/shared_preferences_android.dart';
+```
+<?code-excerpt "readme_excerpts.dart (Android_Options2)"?>
+```dart
+const SharedPreferencesAsyncAndroidOptions options =
+    SharedPreferencesAsyncAndroidOptions(
+        backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences,
+        originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions(
+            fileName: 'the_name_of_a_file'));
+```
+
+The [SharedPreferences] API uses the native [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) tool to store data.
 
 ## Examples
 Here are small examples that show you how to use the API.
@@ -187,7 +203,7 @@ the new prefix otherwise the old preferences will be inaccessible.
 
 | Platform | SharedPreferences | SharedPreferencesAsync/WithCache |
 | :--- | :--- | :--- |
-| Android | SharedPreferences | DataStore Preferences |
+| Android | SharedPreferences | DataStore Preferences or SharedPreferences |
 | iOS | NSUserDefaults | NSUserDefaults |
 | Linux | In the XDG_DATA_HOME directory | In the XDG_DATA_HOME directory |
 | macOS | NSUserDefaults | NSUserDefaults |

packages/shared_preferences/shared_preferences/example/android/app/build.gradle

@@ -30,6 +30,10 @@ android {
         main.java.srcDirs += 'src/main/kotlin'
     }
 
+    kotlinOptions {
+        jvmTarget = '11'
+    }
+
     defaultConfig {
         applicationId "io.flutter.plugins.sharedpreferencesexample"
         minSdkVersion flutter.minSdkVersion

packages/shared_preferences/shared_preferences/example/lib/readme_excerpts.dart

@@ -4,6 +4,9 @@
 
 // ignore_for_file: public_member_api_docs, unused_local_variable, invalid_use_of_visible_for_testing_member
 import 'package:shared_preferences/shared_preferences.dart';
+// #docregion Android_Options1
+import 'package:shared_preferences_android/shared_preferences_android.dart';
+// #enddocregion Android_Options1
 
 Future<void> readmeSnippets() async {
   // #docregion Write
@@ -92,3 +95,11 @@ Future<void> readmeTestSnippets() async {
   SharedPreferences.setMockInitialValues(values);
   // #enddocregion Tests
 }
+
+// #docregion Android_Options2
+const SharedPreferencesAsyncAndroidOptions options =
+    SharedPreferencesAsyncAndroidOptions(
+        backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences,
+        originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions(
+            fileName: 'the_name_of_a_file'));
+// #enddocregion Android_Options2

packages/shared_preferences/shared_preferences/example/pubspec.yaml

@@ -3,8 +3,8 @@ description: Demonstrates how to use the shared_preferences plugin.
 publish_to: none
 
 environment:
-  sdk: ^3.4.0
-  flutter: ">=3.22.0"
+  sdk: ^3.5.0
+  flutter: ">=3.24.0"
 
 dependencies:
   flutter:
@@ -16,6 +16,7 @@ dependencies:
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
     path: ../
+  shared_preferences_android: ^2.4.0
   shared_preferences_platform_interface: ^2.4.0
 
 dev_dependencies:

packages/shared_preferences/shared_preferences/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for reading and writing simple key-value pairs.
   Wraps NSUserDefaults on iOS and SharedPreferences on Android.
 repository: https://github.com/flutter/packages/tree/main/packages/shared_preferences/shared_preferences
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+shared_preferences%22
-version: 2.3.4
+version: 2.3.5
 
 environment:
   sdk: ^3.5.0