diff --git a/cspell.json b/cspell.json index 7627a76a2b7..2e5736a237e 100644 --- a/cspell.json +++ b/cspell.json @@ -532,6 +532,7 @@ "Didfinishlaunchingwithoptions", "displayMode", "displayOrder", + "dists", "DocSet", "DocSets", "Donef", diff --git a/src/fragments/lib/datastore/flutter/getting-started/20_installLib.mdx b/src/fragments/lib/datastore/flutter/getting-started/20_installLib.mdx index e10d4d2f91d..c9767d981dd 100644 --- a/src/fragments/lib/datastore/flutter/getting-started/20_installLib.mdx +++ b/src/fragments/lib/datastore/flutter/getting-started/20_installLib.mdx @@ -20,8 +20,8 @@ compileOptions { // add this line to support Java8 features coreLibraryDesugaringEnabled true - sourceCompatibility JavaVersion.VERSION_1_8 - targetCompatibility JavaVersion.VERSION_1_8 + sourceCompatibility JavaVersion.VERSION_17 + targetCompatibility JavaVersion.VERSION_17 } ``` diff --git a/src/fragments/lib/project-setup/flutter/platform-setup/android.mdx b/src/fragments/lib/project-setup/flutter/platform-setup/android.mdx index 9f00442753b..6bf26008f56 100644 --- a/src/fragments/lib/project-setup/flutter/platform-setup/android.mdx +++ b/src/fragments/lib/project-setup/flutter/platform-setup/android.mdx @@ -1,48 +1,81 @@ -Amplify requires a minimum of API level 24 (Android 7.0), Gradle 7 and Kotlin > 1.9 when targeting Android. +Amplify Flutter supports API level 24+ (Android 7.0+), and requires Gradle 8+, Kotlin 1.9+, and Java 17+ when targeting Android. Follow the steps below to apply these changes in your app. -_If your Flutter app was generated with Flutter 3.16 or lower, please follow the migration guide [here](https://docs.flutter.dev/release/breaking-changes/flutter-gradle-plugin-apply)._ + +The steps below are intended for Flutter apps created with Flutter version 3.16+. If your app was created prior to version 3.16, please follow the guide [here](https://docs.flutter.dev/release/breaking-changes/flutter-gradle-plugin-apply) to migrate to Gradle's declarative plugins block before following the steps below. + -From your project root, navigate to the `android/` directory and open `settings.gradle` in the text editor of your choice. Update the Gradle plugin version to 7.4.2 or higher: +1. Open `android/settings.gradle` and update the Android Gradle plugin and kotlin versions: -```diff - plugins { - id "dev.flutter.flutter-plugin-loader" version "1.0.0" -- id "com.android.application" version "7.3.0" apply false -+ id "com.android.application" version "7.4.2" apply false - id "org.jetbrains.kotlin.android" version "1.9.10" apply false - } +```diff title="android/settings.gradle" +plugins { + id "dev.flutter.flutter-plugin-loader" version "1.0.0" +- id "com.android.application" version "7.3.0" apply false +- id "org.jetbrains.kotlin.android" version "1.7.10" apply false ++ id "com.android.application" version "8.1.0" apply false ++ id "org.jetbrains.kotlin.android" version "1.9.10" apply false +} ``` -Go to the `android/` directory and open `settings.gradle`. Update the Kotlin plugin version to 1.9.10 or higher: - -```diff - plugins { - id "dev.flutter.flutter-plugin-loader" version "1.0.0" - id "com.android.application" version "7.3.0" apply false -- id "org.jetbrains.kotlin.android" version "1.7.10" apply false -+ id "org.jetbrains.kotlin.android" version "1.9.10" apply false - } -``` +2. Open `android/gradle/wrapper/gradle-wrapper.properties` and update the Gradle `distributionUrl`. -Then, open `android/gradle/wrapper/gradle-wrapper.properties`. Update the Gradle `distributionUrl` to a version between 7.3 and 7.6.1 (see the [Flutter docs](https://docs.flutter.dev/release/breaking-changes/android-java-gradle-migration-guide) for more info). - -```diff +```diff title="android/gradle/wrapper/gradle-wrapper.properties" +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-7.0-all.zip -+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.1-all.zip ++distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip ``` -Then, open `android/app/build.gradle`. Update the minimum Android SDK version to 24 or higher: +3. Open `android/app/build.gradle` and update the Java version and minimum Android SDK version. + +```diff title="android/app/build.gradle" +android { + namespace = "com.example.myapp" + compileSdk = flutter.compileSdkVersion + ndkVersion = flutter.ndkVersion + compileOptions { +- sourceCompatibility = JavaVersion.VERSION_1_8 +- targetCompatibility = JavaVersion.VERSION_1_8 ++ sourceCompatibility = JavaVersion.VERSION_17 ++ targetCompatibility = JavaVersion.VERSION_17 + } -```diff defaultConfig { // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html). - applicationId "com.example.myapp" + applicationId = "com.example.myapp" // You can update the following values to match your application needs. // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration. -- minSdkVersion flutter.minSdkVersion -+ minSdkVersion 24 - targetSdkVersion flutter.targetSdkVersion - versionCode flutterVersionCode.toInteger() - versionName flutterVersionName +- minSdk = flutter.minSdkVersion ++ minSdk = 24 + targetSdk = flutter.targetSdkVersion + versionCode = flutterVersionCode.toInteger() + versionName = flutterVersionName } + + buildTypes { + release { + // TODO: Add your own signing config for the release build. + // Signing with the debug keys for now, so `flutter run --release` works. + signingConfig = signingConfigs.debug + } + } +} +``` + + +If you would like to use a higher version of Gradle or Android Gradle plugin see the compatibility matrix [here](https://developer.android.com/build/releases/gradle-plugin#updating-gradle). + + +### Network Permissions for Release Builds + +Flutter apps have access to make network requests by default in debug mode. This permission needs to be added when building in release mode. To do this, open `android/app/src/main/AndroidManifest.xml` and make the following addition. + +```xml title="android/app/src/main/AndroidManifest.xml" + +// highlight-start + +// highlight-end +... + ``` diff --git a/src/fragments/lib/project-setup/flutter/platform-setup/ios.mdx b/src/fragments/lib/project-setup/flutter/platform-setup/ios.mdx index 3d8c79becf4..4a05745764c 100644 --- a/src/fragments/lib/project-setup/flutter/platform-setup/ios.mdx +++ b/src/fragments/lib/project-setup/flutter/platform-setup/ios.mdx @@ -1,4 +1,4 @@ -Amplify requires a minimum deployment target of 13.0 and Xcode 13.2 or higher when targeting iOS. +Amplify requires a minimum deployment target of 13.0 and Xcode 15.0 or higher when targeting iOS. From your project root, navigate to the `ios/` directory and open the `Podfile` in a text editor of your choice. At the top of the file, update the target iOS platform to 13.0 or higher. diff --git a/src/fragments/lib/project-setup/flutter/platform-setup/macos.mdx b/src/fragments/lib/project-setup/flutter/platform-setup/macos.mdx index 2e02deac857..12399795561 100644 --- a/src/fragments/lib/project-setup/flutter/platform-setup/macos.mdx +++ b/src/fragments/lib/project-setup/flutter/platform-setup/macos.mdx @@ -1,4 +1,4 @@ -Amplify requires a minimum deployment target of 10.15 and Xcode 13.2 or higher when targeting macOS. Additionally, you will need to enable networking, keychain entitlements, and code signing. +Amplify requires a minimum deployment target of 10.15 and Xcode 15.0 or higher when targeting macOS. Additionally, you will need to enable networking, keychain entitlements, and code signing. ### Update Minimum Version diff --git a/src/pages/[platform]/start/platform-setup/index.mdx b/src/pages/[platform]/start/platform-setup/index.mdx index 09987d6b6dd..02be15665bf 100644 --- a/src/pages/[platform]/start/platform-setup/index.mdx +++ b/src/pages/[platform]/start/platform-setup/index.mdx @@ -22,38 +22,223 @@ export function getStaticProps(context) { } -### iOS -From your project root, navigate to the `ios/` directory and modify the `Podfile` using a text editor of your choice and update the target iOS platform to 11.0 or higher. +## iOS -```bash -platform :ios, '11.0' +Amplify requires a minimum deployment target of 13.0 and Xcode 15.0 or higher when targeting iOS. Follow the steps below to update the minimum deployment target. + +Open `ios/Podfile` and update the target iOS platform to 13.0 or higher. + + +If there is no file located at `ios/Podfile`, add `amplify_flutter` to your `pubspec.yaml` and run `pub get`. This will automatically create the file. + + +```diff title="ios/Podfile" +- # Uncomment this line to define a global platform for your project +- # platform :ios, '12.0' ++ platform :ios, '13.0' ``` - +Open your project in Xcode and select Runner, Targets -> Runner and then the "General" tab. Under the "Minimum Deployments" section, update the iOS version to 13.0 or higher. + +![Setting the iOS version to 13.0 or higher in the minimum deployments section of the Runner general window.](/images/project-setup/flutter/ios/target-min-deployment-version.png) -When preparing your application for deployment, you should also update your iOS Deployment Target to at least 11.0. See the [Flutter docs](https://docs.flutter.dev/deployment/ios) to learn more about building your iOS app for release. +Select Runner, Project -> Runner and then the "Info" tab. Update "iOS Deployment Target" to 13.0 or higher. +![Setting the iOS version to 13.0 or higher in the deployment targets section of the Runner info window.](/images/project-setup/flutter/ios/project-min-deployment-version.png) + +## Android + +Amplify Flutter supports API level 24+ (Android 7.0+), and requires Gradle 8+, Kotlin 1.9+, and Java 17+ when targeting Android. Follow the steps below to apply these changes in your app. + + +The steps below are intended for Flutter apps created with Flutter version 3.16+. If your app was created prior to version 3.16, please follow the guide [here](https://docs.flutter.dev/release/breaking-changes/flutter-gradle-plugin-apply) to migrate to Gradle's declarative plugins block before following the steps below. -### Android -From your project root, navigate to the `android/app/` directory and modify `build.gradle` using a text editor of your choice and update the target Android SDK version to 21 or higher: +1. Open `android/settings.gradle` and update the Android Gradle plugin and kotlin versions: -```bash -minSdkVersion 21 +```diff title="android/settings.gradle" +plugins { + id "dev.flutter.flutter-plugin-loader" version "1.0.0" +- id "com.android.application" version "7.3.0" apply false +- id "org.jetbrains.kotlin.android" version "1.7.10" apply false ++ id "com.android.application" version "8.1.0" apply false ++ id "org.jetbrains.kotlin.android" version "1.9.10" apply false +} ``` - +2. Open `android/gradle/wrapper/gradle-wrapper.properties` and update the Gradle `distributionUrl`. -If you are using Flutter 2.10 or above, you will need to ensure that your app supports an [up-to-date Kotlin version](https://docs.flutter.dev/release/breaking-changes/kotlin-version). -This will typically be version 1.5.31 or higher. -
-You can do this by updating the Kotlin version in your app's `android/build.gradle` file: +```diff title="android/gradle/wrapper/gradle-wrapper.properties" +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists +-distributionUrl=https\://services.gradle.org/distributions/gradle-7.0-all.zip ++distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip +``` -```yaml -buildscript { - ext.kotlin_version = '1.5.31' - ... +3. Open `android/app/build.gradle` and update the Java version and minimum Android SDK version. + +```diff title="android/app/build.gradle" +android { + namespace = "com.example.myapp" + compileSdk = flutter.compileSdkVersion + ndkVersion = flutter.ndkVersion + compileOptions { +- sourceCompatibility = JavaVersion.VERSION_1_8 +- targetCompatibility = JavaVersion.VERSION_1_8 ++ sourceCompatibility = JavaVersion.VERSION_17 ++ targetCompatibility = JavaVersion.VERSION_17 + } + + defaultConfig { + // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html). + applicationId = "com.example.myapp" + // You can update the following values to match your application needs. + // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration. +- minSdk = flutter.minSdkVersion ++ minSdk = 24 + targetSdk = flutter.targetSdkVersion + versionCode = flutterVersionCode.toInteger() + versionName = flutterVersionName + } + + buildTypes { + release { + // TODO: Add your own signing config for the release build. + // Signing with the debug keys for now, so `flutter run --release` works. + signingConfig = signingConfigs.debug + } + } } ``` + +If you would like to use a higher version of Gradle or Android Gradle plugin see the compatibility matrix [here](https://developer.android.com/build/releases/gradle-plugin#updating-gradle). + + +### Network Permissions for Release Builds + +Flutter apps have access to make network requests by default in debug mode. This permission needs to be added when building in release mode. To do this, open `android/app/src/main/AndroidManifest.xml` and make the following addition. + +```xml title="android/app/src/main/AndroidManifest.xml" + +// highlight-start + +// highlight-end +... + +``` + +## Web + +There are no Amplify specific requirements or setup instructions when targeting web. You will need to use a browser supported by Flutter. See the following Flutter docs for more info: + +- [Supported deployment platforms](https://docs.flutter.dev/reference/supported-platforms) +- [FAQ: Which web browsers are supported by Flutter?](https://docs.flutter.dev/development/platform-integration/web/faq#which-web-browsers-are-supported-by-flutter) + +## macOS + +Amplify requires a minimum deployment target of 10.15 and Xcode 15.0 or higher when targeting macOS. Additionally, you will need to enable networking, keychain entitlements, and code signing. + +### Update Minimum Version + +Open `macos/Podfile` and update the target macOS platform to 10.15 or higher. + + +If there is no file located at `macos/Podfile`, add `amplify_flutter` to your `pubspec.yaml` and run `pub get`. This will automatically create the file. + +```diff title="ios/Podfile" +- platform :osx, '10.14' ++ platform :osx, '10.15' +``` + +Open your project in Xcode and select Runner, Targets -> Runner and then the "General" tab. Under the "Minimum Deployments" section, update the macOS version to 10.15 or higher. + +![Setting the macOS version to 10.15 or higher in the Minimum Deployments tab of the Runner general section.](/images/project-setup/flutter/mac/target-min-deployment-version.png) + +Select Runner, Project -> Runner and then the "Info" tab. Update "macOS Deployment Target" to 10.15 or higher. + +![Setting the macOS version to 10.15 or higher in the macOS Deployment Target tab of the Runner info section.](/images/project-setup/flutter/mac/project-min-deployment-version.png) + +### Enable Network Calls + +Open your project in Xcode and select Runner, Targets -> Runner and then the "Signing and Capabilities" tab. Under "App Sandbox" select "Outgoing Connections (Client)". + +![Selecting outgoing connections in the app sandbox section of the runner signing and capabilities tab.](/images/project-setup/flutter/mac/xcode-entitlements.png) + +For more info on the Networking entitlement, see Apple's documentation on [com.apple.security.network.client](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_network_client). + +### Enable Keychain Sharing + + + +This capability is required because Amplify uses the Data Protection Keychain on macOS as a platform best practice. +See [TN3137: macOS keychain APIs and implementations](https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains) +for more information on how Keychain works on macOS and the Keychain Sharing entitlement. + + + +Open your project in Xcode and select Runner, Targets -> Runner and then the "Signing and Capabilities" tab. + +1. Click the "+ icon". + +![Plus icon circled in the signing and capabilities section of the runner tab.](/images/project-setup/flutter/mac/enable-keychain-access.png) + +2. Search for "Keychain Sharing" in the subsequent modal, and add it. + +![Keychain Sharing search result after searching keychain.](/images/project-setup/flutter/mac/search-keychain-sharing.png) + +3. Scroll down to "Keychain Sharing" in the "Signing and Capabilities" and click the "+" icon. By default, your bundle ID will be used. + +![Plus icon highlighted in the keychain sharing section of the signing and capabilities section of runner.](/images/project-setup/flutter/mac/adding-keychain-access-group.png) + +4. Finally, add a development team and enable signing. + +![Team selector and Enable Development Signing button highlighted in the signing and capabilities section of the runner tab.](/images/project-setup/flutter/mac/enable-signing.png) + + +## Windows + +There are no Amplify specific requirements or setup instructions when targeting Windows. You will need to use a Windows version supported by Flutter. See the following Flutter docs for more info: + +- [Supported deployment platforms](https://docs.flutter.dev/reference/supported-platforms) + +## Linux + +Amplify Flutter depends on the [libsecret](https://wiki.gnome.org/Projects/Libsecret) library when targeting Linux. + +### Local Development + +To run and debug an app that depends on Amplify Flutter, you must install `libsecret-1-dev`. Run the following commands to install `libsecret-1-dev`. this will also install dependencies of `libsecret-1-dev`, such as `libglib2.0-dev`. + + + The command below is intended for Ubuntu. The command may vary on other Linux distributions. + + +{/* cSpell:disable */} + +```terminal +sudo apt-get update +sudo apt-get install -y libsecret-1-dev +``` + +{/* cSpell:enable */} + +### Packaging Your App + +To include the required dependencies when packaging your app with Snapcraft, include them in your `snapcraft.yaml` file. For more info, see [Flutter's documentation on releasing to the Snap Store](https://docs.flutter.dev/deployment/linux). + +```yaml +parts: + my-app: + plugin: flutter + source: . + flutter-target: lib/main.dart + build-packages: + - libsecret-1-dev + stage-packages: + - libsecret-1-0 +``` +