chore: update readme and changelog (#79)

logto-io · Jan 23, 2025 · 70071b3 · 70071b3
1 parent 41dfe52
commit 70071b3
Show file tree

Hide file tree

Showing 2 changed files with 173 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,89 @@
+## 3.0.0
+
+### Dependencies update
+
+1. Switch to flutter_web_auth_2 package
+   Replace the legacy [flutter_web_auth](https://pub.dev/packages/flutter_web_auth) package with the new [flutter_web_auth_2](https://pub.dev/packages/flutter_web_auth_2). Since the `flutter_web_auth` package is no longer maintained, we have to switch to the new package to support the latest Flutter versions.
+
+   **flutter_web_auth_2** setup guide:
+
+   - iOS: No additional setup required
+   - Android: In order to capture the callback URL. You wil need to add the following activity to your AndroidManifest.xml file. Replace `YOUR_CALLBACK_URL_SCHEME_HERE` with your actual callback URL scheme (io.logto etc.).
+
+     ```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>
+     ```
+
+     Remove any `android:taskAffinity` entries and add set `android:launchMode="singleTop"` to the main activity in the AndroidManifest.xml file.
+
+   - Web: Create a new endpoint to capture the callback URL and sent it back to the application using `postMessage` API. The endpoint should be the same as the `redirectUri` parameter in the `signIn` method.
+
+     ```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>
+     ```
+
+     Please check the setup guide in the [flutter_web_auth_2](https://pub.dev/packages/flutter_web_auth_2#setup) package for more details.
+
+2. Other patches
+   - bump crypto package
+   - bump jose package
+   - bump json_annotation package
+
+### New features
+
+1. With the latest `flutter_web_auth_2` package, this SDK now supports the Web platform. You can use Logto dart SDK in your Flutter web projects as well. Officially supported platforms are iOS, Android, and Web.
+
+### Bug fixes
+
+1. Fix the namespace missing issue when building with the latest Gradle version on Android. ([#75](https://github.com/logto-io/dart/issues/75))
+2. Fix the issue that the webview is not closing after the user completes the OAuth2 authorization flow on Android. ([60](https://github.com/logto-io/dart/issues/60))
+3. Fix the issue on Android that the sign-in session is not cleared after the user signs out.
+
+### Breaking changes
+
+`logtoClient.signOut` method now requires a `redirectUri` parameter. 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.
+
+User experience on iOS will not be affected by this change, but for Android and Web platforms, when users click the sign-out button, an `end_session` request will be triggered by opening a webview with the `post_logout_redirect_uri` parameter set to the `redirectUri` value. This will clear the sign-in session and redirect the user back to the `redirectUri` page.
+
 ## 2.1.0
 
 ### New features

diff --git a/README.md b/README.md
@@ -6,23 +6,100 @@
   <span><i><a href="https://logto.io" target="_blank">Logto</a> helps you quickly focus on everything after signing in.</i></span>
 </p>
 
-# Logto Flutter SDKs
+# Logto Flutter SDK
 
 [![Build Status](https://github.com/logto-io/kotlin/actions/workflows/main.yml/badge.svg)](https://github.com/logto-io/dart/actions/workflows/main.yml)
 
-Logto's flutter SDK for native apps.
+This project is the official Flutter SDK for [Logto](https://logto.io). It provides a simple way to integrate Logto into your Flutter project.
 
-[pub.dev](https://pub.dev/packages/logto_dart_sdk)
+In the background, this SDK uses the [flutter_web_auth_2](https://pub.dev/packages/flutter_web_auth_2) package to handle the OAuth2 flow.
 
-## Packages
+## Installation
 
-- logto_core: Core SDK is used for generation dart project with basic API and util method provided.
-- logto_client: Client SDK for flutter native apps. Built based on logto_core with user sign-in interaction flow integrated
+Add the following dependencies to your `pubspec.yaml` file:
 
-## Platforms
+```yaml
+dependencies:
+  logto_dart_sdk: ^3.0.0
+```
 
-iOS, Android
+Then run `flutter pub get` to install the package.
 
-## Integration Guide
+Or directly install the package by running:
 
-[Flutter SDK tutorial](https://docs.logto.io/sdk/flutter/)
+```bash
+flutter pub add logto_dart_sdk
+```
+
+Check out the package on [pub.dev](https://pub.dev/packages/logto_dart_sdk).
+
+## Setup
+
+- iOS: No additional setup required.
+- [Android](https://github.com/ThexXTURBOXx/flutter_web_auth_2?tab=readme-ov-file#android).
+- [Web](https://github.com/ThexXTURBOXx/flutter_web_auth_2?tab=readme-ov-file#web)
+
+Learn more about the [flutter_web_auth_2 setup](https://github.com/ThexXTURBOXx/flutter_web_auth_2?tab=readme-ov-file#setup).
+
+## Usages
+
+### Init Logto SDK
+
+```dart
+  final logtoConfig = const LogtoConfig(
+    endpoint: "<your-logto-endpoint>",
+    appId: "<your-app-id>"
+  );
+
+  void _init() {
+    logtoClient = LogtoClient(
+      config: logtoConfig,
+      httpClient: http.Client(), // Optional http client
+    );
+    render();
+  }
+```
+
+### Sign in and sign out
+
+```dart
+  // Sign in
+  await logtoClient.signIn(redirectUri);
+
+  // Sign out
+  await logtoClient.signOut(redirectUri);
+```
+
+### Full SDK documentation
+
+Check [Flutter SDK guide](https://docs.logto.io/quick-starts/flutter) for more details.
+
+## Supported platforms
+
+iOS, Android, Web
+
+## Migration guide
+
+:::note
+For SDK version before 3.0.0, this SDK uses the [flutter_web_auth](https://pub.dev/packages/flutter_web_auth) package.
+:::
+
+1. Upgrade to the latest version
+
+```yaml
+dependencies:
+  logto_dart_sdk: ^3.0.0
+```
+
+2. Update the manifest files (Android platform only)
+
+Replace the flutter_web_auth callback activity with the new `flutter_web_auth_2` in the AndroidManifest.xml file.
+
+- FlutterWebAuth -> FlutterWebAuth2
+- flutter_web_auth -> flutter_web_auth_2
+
+3. `redirectUri` parameter is now required for the `signOut` method.
+
+```dart
+await logtoClient.signOut(redirectUri);
+```