feat: update flutter SDK doc (#986)

* feat: update flutter SDK doc update flutter SDK doc * chore: remove headings ID remove flutter heading ID * chore: add heading ids * feat: add i18n translations add i18n translations * chore: add missing assets add missing asserts * fix: fix translated files fix translated files --------- Co-authored-by: Charles Zhao <[email protected]>
logto-io · Jan 26, 2025 · ebe2969 · ebe2969
1 parent be86013
commit ebe2969
Show file tree

Hide file tree

Showing 59 changed files with 1,214 additions and 585 deletions.
diff --git a/docs/quick-starts/assets/flutter-post-sign-out-redirect-uri.png b/docs/quick-starts/assets/flutter-post-sign-out-redirect-uri.png
diff --git a/docs/quick-starts/assets/flutter-redirect-uri.png b/docs/quick-starts/assets/flutter-redirect-uri.png
diff --git a/docs/quick-starts/framework/flutter/README.mdx b/docs/quick-starts/framework/flutter/README.mdx
@@ -35,6 +35,8 @@ This tutorial will show you how to integrate Logto into your Flutter application
 
 <Installation />
 
+## Set up \{#set-up}
+
 <Dependency />
 
 ## Integration \{#integration}
@@ -51,6 +53,71 @@ This tutorial will show you how to integrate Logto into your Flutter application
 
 <Organization />
 
+## Migration guide \{#migration-guide}
+
+If you are migration from a previous version of Logto Dart SDK, version < 3.0.0:
+
+1. Update your `pubspec.yaml` file to use the latest version of the Logto Dart SDK.
+
+   ```yaml title="pubspec.yaml"
+   dependencies:
+     logto_dart_sdk: ^3.0.0
+   ```
+
+2. Update the Android manifest file, replace the legacy `flutter_web_auth` callback activity with the new `flutter_web_auth_2`.
+
+   - `FlutterWebAuth` -> `FlutterWebAuth2`
+   - `flutter_web_auth` -> `flutter_web_auth_2`
+
+3. Pass the `redirectUri` to the `signOut` method.
+
+   `redirectUri` is now required when calling the `signOut` method. For iOS platform, this parameter is useless, but for Android and Web platforms which require an additional `end_session` request to clean up the sign-in session, this parameter will be used as the `post_logout_redirect_uri` parameter in the `end_session` request.
+
+   ```dart
+   await logtoClient.signOut(redirectUri);
+   ```
+
+## Troubleshooting \{#troubleshooting}
+
+### Troubleshooting Android \{#troubleshooting-android}
+
+- You will need to update your AndroidManifest.xml to include the `com.linusu.flutter_web_auth_2.CallbackActivity` activity, something like:
+
+  ```xml title="android/app/src/main/AndroidManifest.xml"
+    <manifest>
+    <application>
+
+      <!-- add the com.linusu.flutter_web_auth_2.CallbackActivity activity -->
+      <activity
+        android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
+        android:exported="true">
+        <intent-filter android:label="flutter_web_auth_2">
+          <action android:name="android.intent.action.VIEW" />
+          <category android:name="android.intent.category.DEFAULT" />
+          <category android:name="android.intent.category.BROWSABLE" />
+          <data android:scheme="YOUR_CALLBACK_URL_SCHEME_HERE" />
+        </intent-filter>
+      </activity>
+
+    </application>
+  </manifest>
+  ```
+
+- If you are targeting S+ (SDK version 31 and above) you need to provide an explicit value for `android:exported`. If you followed earlier installation instructions, this was not included. Make sure that you add `android:exported="true"` to the `com.linusu.flutter_web_auth.CallbackActivity` activity in your `AndroidManifest.xml` file.
+
+- Browser not closed after successful sign-in:
+
+  In order to ensure the `flutter_web_auth_2` works correctly, you need to remove any `android:taskAffinity` entries from your `AndroidManifest.xml` file. Set `android:launchMode="singleTop"` to the main activity in your `AndroidManifest.xml` file.
+
+  ```xml title="android/app/src/main/AndroidManifest.xml"
+  <activity
+    android:name=".MainActivity"
+    android:launchMode="singleTop"
+    android:theme="@style/LaunchTheme"
+    // ...
+  />
+  ```
+
 ## Further readings \{#further-readings}
 
 <FurtherReadings />
diff --git a/docs/quick-starts/framework/flutter/_dependency.mdx b/docs/quick-starts/framework/flutter/_dependency.mdx
@@ -1,22 +1,21 @@
-### Dependency and configurations \{#dependency-and-configurations}
+### SDK version compatibility \{#sdk-version-compatibility}
 
-This SDK has the following dependencies, some require additional configurations:
+| Logto SDK version | Dart SDK version  | Dart 3.0 compatible |
+| ----------------- | ----------------- | ------------------- |
+| < 2.0.0           | >= 2.17.6 < 3.0.0 | false               |
+| >= 2.0.0 < 3.0.0  | >= 3.0.0          | true                |
+| >= 3.0.0          | >= 3.6.0          | true                |
 
-<details>
-<summary>
+### flutter_secure_storage set up \{#flutter_secure_storage-set-up}
 
-### flutter_secure_storage \{#flutter_secure_storage}
-
-</summary>
-
-We use [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage) to implement the cross-platform persistent secure token storage.
+Under the hood, this SDK uses [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage) to implement the cross-platform persistent secure token storage.
 
 - Keychain is used for iOS
 - AES encryption is used for Android.
 
 #### Config Android version \{#config-android-version}
 
-Set the android:minSdkVersion to 18 in your project's android/app/build.gradle file.
+Set the android:minSdkVersion to `>= 18` in your project's `android/app/build.gradle` file.
 
 ```kotlin title="build.gradle"
   android {
@@ -30,11 +29,9 @@ Set the android:minSdkVersion to 18 in your project's android/app/build.gradle f
   }
 ```
 
-#### Disable autobackup \{#disable-autobackup}
-
-By default Android may backup data on Google Drive automatically. It can cause exception `java.security.InvalidKeyException:Failed to unwrap key`.
+#### Disable auto backup on Android \{#disable-auto-backup-on-android}
 
-To avoid this, you can disable auto backup for your app or exclude `sharedprefs` from the `FlutterSecureStorage`.
+By default Android backups data on Google Drive. It can cause exception `java.security.InvalidKeyException:Failed` to unwrap key. To avoid this,
 
 1. To disable auto backup, go to your app manifest file and set the `android:allowBackup` and `android:fullBackupContent` attributes to `false`.
 
@@ -76,51 +73,62 @@ To avoid this, you can disable auto backup for your app or exclude `sharedprefs`
 
 Please check [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage#configure-android-version) for more details.
 
-</details>
-
-<details>
-  <summary>
-
-### flutter_web_auth \{#flutter_web_auth}
+### flutter_web_auth_2 set up \{#flutter_web_auth_2-set-up}
 
-</summary>
+Behind the scenes, this SDK uses [flutter_web_auth_2](https://pub.dev/packages/flutter_web_auth_2) to authenticate users with Logto. This package provides a simple way to authenticate users with Logto using the system webview or browser.
 
-[flutter_web_auth](https://pub.dev/packages/flutter_web_auth) is used behind Logto's flutter SDK. We rely on its webview-based interaction interface to authenticate users.
-
-:::note
 This plugin uses `ASWebAuthenticationSession` on iOS 12+ and macOS 10.15+, `SFAuthenticationSession` on iOS 11, `Chrome Custom Tabs` on Android and opens a new window on Web.
-:::
-
-#### Register the callback url on Android \{#register-the-callback-url-on-android}
-
-In order to capture the callback url from Logto's sign-in web page, you will need to register your sign-in redirectUri to your `AndroidManifest.xml` file.
-
-```xml title="AndroidManifest.xml"
-<activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
-    <intent-filter android:label="flutter_web_auth">
-        <action android:name="android.intent.action.VIEW"/>
-        <category android:name="android.intent.category.DEFAULT"/>
-        <category android:name="android.intent.category.BROWSABLE"/>
-        <data android:scheme="io.logto"/>
-    </intent-filter>
-</activity>
-```
-
-</details>
-
-<details>
-  <summary>
-
-### http.dart \{#httpdart}
-
-</summary>
 
-Since the SDK need to make network requests, you will need to pass in a HTTP client to the SDK. You can use the default `http.Client` from [http.dart](https://pub.dev/packages/http) or create your own `http.Client` with custom configurations.
-
-```dart
-
-  import 'package:http/http.dart' as http;
+- iOS: No additional setup required
+
+- Android: Register the callback url on Android
+
+  In order to capture the callback url from Logto's sign-in web page, you will need to register your sign-in redirectUri to your `AndroidManifest.xml` file.
+
+  ```xml title="AndroidManifest.xml"
+    <manifest>
+      <application>
+          <activity
+            android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
+            android:exported="true">
+            <intent-filter android:label="flutter_web_auth_2">
+            <action android:name="android.intent.action.VIEW" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+            <data android:scheme="YOUR_CALLBACK_URL_SCHEME_HERE" />
+            </intent-filter>
+          </activity>
+      </application>
+    </manifest>
+  ```
+
+- Web browser: Create an endpoint to handle the callback URL
+
+  If you are using the web platform, you need to create an endpoint to handle the callback URL and send it back to the application using the `postMessage` API.
+
+  ```html title="callback.html"
+  <!doctype html>
+  <title>Authentication complete</title>
+  <p>Authentication is complete. If this does not happen automatically, please close the window.</p>
+  <script>
+    function postAuthenticationMessage() {
+      const message = {
+        'flutter-web-auth-2': window.location.href,
+      };
+
+      if (window.opener) {
+        window.opener.postMessage(message, window.location.origin);
+        window.close();
+      } else if (window.parent && window.parent !== window) {
+        window.parent.postMessage(message, window.location.origin);
+      } else {
+        localStorage.setItem('flutter-web-auth-2', window.location.href);
+        window.close();
+      }
+    }
 
-```
+    postAuthenticationMessage();
+  </script>
+  ```
 
-</details>
+Please check the setup guide in the [flutter_web_auth_2](https://pub.dev/packages/flutter_web_auth_2#setup) package for more details.
diff --git a/docs/quick-starts/framework/flutter/_installation.mdx b/docs/quick-starts/framework/flutter/_installation.mdx
@@ -9,7 +9,20 @@ You can install the `logto_dart_sdk package` directly using the pub package mana
 Run the following command under your project root:
 
 ```bash
-flutter pub get logto_dart_sdk
+flutter pub add logto_dart_sdk
+```
+
+Or add the following to your `pubspec.yaml` file:
+
+```yaml
+dependencies:
+  logto_dart_sdk: ^3.0.0
+```
+
+Then run:
+
+```bash
+flutter pub get
 ```
 
 </TabItem>
@@ -25,11 +38,3 @@ git clone https://github.com/logto-io/dart
 </TabItem>
 
 </Tabs>
-
-### Modules \{#modules}
-
-The `logto_dart_sdk` includes two main modules:
-
-- **logto_core.dart** This core module provides the basic functions and interfaces for the Logto SDK.
-
-- **logto_client.dart** This client module offers a high-level Logto client class for interacting with the Logto server.
diff --git a/docs/quick-starts/framework/flutter/_integration.mdx b/docs/quick-starts/framework/flutter/_integration.mdx
@@ -1,5 +1,7 @@
-import redirectUriFigure from '../../assets/ios-redirect-uri.png';
+import postSignOutRedirectUriFigure from '../../assets/flutter-post-sign-out-redirect-uri.png';
+import redirectUriFigure from '../../assets/flutter-redirect-uri.png';
 import Checkpoint from '../../fragments/_checkpoint-test-your-application.md';
+import ConfigurePostSignOutRedirectUri from '../../fragments/_configure-post-sign-out-redirect-uri.mdx';
 import ConfigureRedirectUri from '../../fragments/_configure-redirect-uri.mdx';
 import SignInFlowSummary from '../../fragments/_web-sign-in-flow-summary.mdx';
 
@@ -121,20 +123,27 @@ class _MyHomePageState extends State<MyHomePage> {
 
 ### Implement sign-out \{#implement-sign-out}
 
+<ConfigurePostSignOutRedirectUri
+  figureSrc={postSignOutRedirectUriFigure}
+  postSignOutRedirectUri="io.logto://callback"
+/>
+
 Now let's add a sign-out button on the main page so users can sign out from your application.
 
 ```dart title="lib/main.dart"
 class _MyHomePageState extends State<MyHomePage> {
   // ...
 
+  final postSignOutRedirectUri = 'io.logto//home';
+
   @override
   Widget build(BuildContext context) {
     // ...
 
     Widget signOutButton = TextButton(
       onPressed: () async {
         // highlight-start
-        await logtoClient.signOut();
+        await logtoClient.signOut(postSignOutRedirectUri);
         render();
         // highlight-end
       },

diff --git a/docs/quick-starts/framework/flutter/_tip.md b/docs/quick-starts/framework/flutter/_tip.md
@@ -1,8 +1,7 @@
 :::tip
 
 - The SDK package is available on [pub.dev](https://pub.dev/packages/logto_dart_sdk) and Logto [GitHub repository](https://github.com/logto-io/dart).
-- The sample project is built using [Flutter material](https://flutter.dev). You can find it on [pub.dev](https://pub.dev/packages/logto_dart_sdk/example) and our [GitHub repository](https://github.com/logto-io/dart).
-- The SDK is compatible with Android, and iOS platforms only.
-- The SDK v1.x is compatible with Dart 2.x. For SDK v2.x, you need to update your Dart version to 3.x or higher.
+- The sample project is built using [Flutter material](https://flutter.dev). You can find it on [pub.dev](https://pub.dev/packages/logto_dart_sdk/example).
+- This SDK is compatible with Flutter applications on iOS, Android, and Web platforms. Compatibility with other platforms has not been tested.
 
 :::
diff --git a/...content-docs/current/quick-starts/assets/flutter-post-sign-out-redirect-uri.png b/...content-docs/current/quick-starts/assets/flutter-post-sign-out-redirect-uri.png
diff --git a/...saurus-plugin-content-docs/current/quick-starts/assets/flutter-redirect-uri.png b/...saurus-plugin-content-docs/current/quick-starts/assets/flutter-redirect-uri.png