From 70071b320367c8a9692ba321d8a1fe94ad01d734 Mon Sep 17 00:00:00 2001 From: simeng-li Date: Thu, 23 Jan 2025 14:58:43 +0800 Subject: [PATCH] chore: update readme and changelog (#79) --- CHANGELOG.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 173 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 906ced1..6ccdad3 100644 --- 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 + + + + + + + + + + + + + + + ``` + + 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 + + Authentication complete +

+ Authentication is complete. If this does not happen automatically, please + close the window. +

+ + ``` + + 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 index afbeeaf..ed31654 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,100 @@ Logto helps you quickly focus on everything after signing in.

-# 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: "", + appId: "" + ); + + 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); +```