docs: improve readme (#539)

* docs: improve readme

* fix: typo

* fix: update readme

README.md

@@ -43,13 +43,19 @@ dart pub add flutter_stripe
 
 #### Android
 
-- Android 5.0 (API level 21) and above
-- Kotlin version 1.5.0 and above: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/build.gradle#L2)
-- Using a descendant of `Theme.AppCompat` for your activity: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/app/src/main/res/values/styles.xml#L15), [example night theme](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/app/src/main/res/values-night/styles.xml#L16)
-- Using an up-to-date Android gradle build tools version: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/build.gradle#L9) and an up-to-date gradle version accordingly: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/gradle/wrapper/gradle-wrapper.properties#L6) 
-- Using `FlutterFragmentActivity` instead of `FlutterActivity` in `MainActivity.kt`: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/app/src/main/kotlin/com/flutter/stripe/example/MainActivity.kt#L6)
 
-This is caused by the Stripe SDK requires the use of the AppCompat theme for their UI components and the Support Fragment Manager for the Payment Sheets
+This plugin requires several changes to be able to work on Android devices. Please make sure you follow all these steps:
+
+1. Use Android 5.0 (API level 21) and above
+2. Use Kotlin version 1.5.0 and above: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/build.gradle#L2)
+3. Using a descendant of `Theme.AppCompat` for your activity: [example](https://github.com/flutter-stripe/flutter_stripe/main/example/android/app/src/main/res/values/styles.xml#L15), [example night theme](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/app/src/main/res/values-night/styles.xml#L16)
+4. Using an up-to-date Android gradle build tools version: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/build.gradle#L9) and an up-to-date gradle version accordingly: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/gradle/wrapper/gradle-wrapper.properties#L6) 
+5. Using `FlutterFragmentActivity` instead of `FlutterActivity` in `MainActivity.kt`: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/app/src/main/kotlin/com/flutter/stripe/example/MainActivity.kt#L6)
+6. Rebuild the app, as the above changes don't update with hot reload
+
+These changes are needed because the Android Stripe SDK requires the use of the AppCompat theme for their UI components and the Support Fragment Manager for the Payment Sheets
+
+If you are having troubles to make this package to work on Android, join [this discussion](https://github.com/flutter-stripe/flutter_stripe/discussions/538) to get some support 
 
 #### iOS
 
@@ -61,8 +67,21 @@ Now you can use Stripe with Flutter web! Notice right now it is highly experimen
 
 Check the steps needed [here](https://github.com/flutter-stripe/flutter_stripe/tree/main/packages/stripe_web)
 
+## Usage
+
+The library provides three UI componets for accepting card payments: the `CardField`, `CardForm`, and the `Paymentsheet`. 
+
+We recommend using the `PaymentSheet` for the most easy and smooth Stripe integration. It provides out of the box support for:
+- Localized labels and error messages to the users
+- Build-in animations
+- Build-in Google Pay and Apple Pay buttons
+- Handling 3D-secure
+
+Notice that `PaymentSheet` is only available for Android and iOS.
+
+On the other side the `CardField` allows you to create a more customizable payment flow inside your app.
 
-## Usage example
+### Example
 
 ```dart
 // main.dart

packages/stripe/README.md

@@ -43,13 +43,18 @@ dart pub add flutter_stripe
 
 #### Android
 
-- Android 5.0 (API level 21) and above
-- Kotlin version 1.5.0 and above: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/build.gradle#L2)
-- Using a descendant of `Theme.AppCompat` for your activity: [example](https://github.com/flutter-stripe/flutter_stripe/main/example/android/app/src/main/res/values/styles.xml#L15), [example night theme](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/app/src/main/res/values-night/styles.xml#L16)
-- Using an up-to-date Android gradle build tools version: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/build.gradle#L9) and an up-to-date gradle version accordingly: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/gradle/wrapper/gradle-wrapper.properties#L6) 
-- Using `FlutterFragmentActivity` instead of `FlutterActivity` in `MainActivity.kt`: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/app/src/main/kotlin/com/flutter/stripe/example/MainActivity.kt#L6)
+This plugin requires several changes to be able to work on Android devices. Please make sure you follow all these steps:
 
-This is caused by the Stripe SDK requires the use of the AppCompat theme for their UI components and the Support Fragment Manager for the Payment Sheets
+1. Use Android 5.0 (API level 21) and above
+2. Use Kotlin version 1.5.0 and above: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/build.gradle#L2)
+3. Using a descendant of `Theme.AppCompat` for your activity: [example](https://github.com/flutter-stripe/flutter_stripe/main/example/android/app/src/main/res/values/styles.xml#L15), [example night theme](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/app/src/main/res/values-night/styles.xml#L16)
+4. Using an up-to-date Android gradle build tools version: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/build.gradle#L9) and an up-to-date gradle version accordingly: [example](https://github.com/flutter-stripe/flutter_stripe/blob/main/example/android/gradle/wrapper/gradle-wrapper.properties#L6) 
+5. Using `FlutterFragmentActivity` instead of `FlutterActivity` in `MainActivity.kt`: [example](https://github.com/flutter-stripe/flutter_stripe/blob/79b201a2e9b827196d6a97bb41e1d0e526632a5a/example/android/app/src/main/kotlin/com/flutter/stripe/example/MainActivity.kt#L6)
+6. Rebuild the app, as the above changes don't update with hot reload
+
+These changes are needed because the Android Stripe SDK requires the use of the AppCompat theme for their UI components and the Support Fragment Manager for the Payment Sheets
+
+If you are having troubles to make this package to work on Android, join [this discussion](https://github.com/flutter-stripe/flutter_stripe/discussions/538) to get some support 
 
 #### iOS
 
@@ -61,18 +66,19 @@ Now you can use Stripe with Flutter web! Notice right now it is highly experimen
 
 Check the steps needed [here](https://github.com/flutter-stripe/flutter_stripe/tree/main/packages/stripe_web)
 
-
 ## Usage
 
-The library supports 2 ways of payment namely the `CardField` and the `Paymentsheet`. The `CardField` has the most configurable options but it has some issues on Android: https://github.com/flutter/flutter/issues/86480 .  
+The library provides three UI componets for accepting card payments: the `CardField`, `CardForm`, and the `Paymentsheet`. 
 
-Furthermore the `PaymentSheet` has a more easy and out of the box integration:
+We recommend using the `PaymentSheet` for the most easy and smooth Stripe integration. It provides out of the box support for:
 - Localized labels and error messages to the users
 - Build-in animations
 - Build-in Google Pay and Apple Pay buttons
-- Handling 3D-secure 
+- Handling 3D-secure
+
+Notice that `PaymentSheet` is only available for Android and iOS.
 
-We recommend using the `PaymentSheet` for the most easy and smooth Stripe integration.
+On the other side the `CardField` allows you to create a more customizable payment flow inside your app.
 
 ### Example
 

packages/stripe_android/android/src/main/kotlin/com/flutter/stripe/StripeAndroidPlugin.kt

@@ -72,7 +72,8 @@ class StripeAndroidPlugin : FlutterPlugin, MethodCallHandler, ActivityAware {
                 "flutter_stripe initialization failed",
                 """The plugin failed to initialize:
 ${initializationError}
-Please check the README: https://github.com/flutter-stripe/flutter_stripe#android""",
+Please make sure you follow all the steps detailed inside the README: https://github.com/flutter-stripe/flutter_stripe#android
+If you continue to have trouble, follow this discussion to get some support https://github.com/flutter-stripe/flutter_stripe/discussions/538""",
                 null
             )
             return

tools/clone_readme.sh

@@ -0,0 +1 @@
+cp 'README.md' "packages/stripe/README.md"