菜单

Flutter模式接入

下载

RootAuth Flutter 接入指南

本包提供无 UI 的 RootAuth API 客户端。应用负责表单、提示、回调和授权码交换；原生 Google 登录目前仅支持 Android。

1. 安装

要求 Flutter >= 3.29.0、Dart >= 3.7.0。在应用的 pubspec.yaml 中添加依赖，然后运行 flutter pub get：

yaml 复制代码

dependencies:
  rootauth_flutter:
    git:
      url: http://gitlab.standard-software.co/rootauth-public/rootauth-flutter-package.git
      ref: main

2. 创建客户端

dart 复制代码

import 'package:rootauth_flutter/rootauth_flutter.dart';

final auth = RootAuthClient(const RootAuthConfig(
  appId: 'your-app-id',
  redirectUri: 'https://your-app.example/callback',
  locale: 'zh-CN',
));

RootAuthConfig 参数：

参数	类型	必填	默认值	说明
`appId`	`String`	是	无	应用 ID，不能为空。
`redirectUri`	`String`	是	无	已登记的回调地址；Google 登录要求 HTTPS。
`apiBaseUrl`	`String`	否	`https://rootauth-api.rootauth.com`	API 地址，必须使用 HTTPS。
`scope`	`List<String>`	否	`['openid']`	OIDC 范围。
`locale`	`String`	否	`en-US`	请求语言，如 `zh-CN`。
`grantType`	`String`	否	`authorization_code`	授权模式。
`state`	`String`	否	`''`	回调状态值。

RootAuthClient(config, {httpClient, tokenStore, captchaHandler, googleIdentityProvider, urlLauncher}) 参数：

参数	类型	说明
`config`	`RootAuthConfig`	必填，见上表。
`httpClient`	`http.Client?`	可选；注入后由应用关闭。
`tokenStore`	`TokenStore?`	可选；默认 `SecureTokenStore()`。
`captchaHandler`	`CaptchaHandler?`	可选；服务端启用验证码时必须提供。
`googleIdentityProvider`	`GoogleIdentityProvider?`	可选；默认 Android 原生实现。
`urlLauncher`	`RootAuthUrlLauncher?`	可选；类型为 `Future<bool> Function(Uri uri, LaunchMode mode)`。

3. 调用约定

JsonMap 是 Map<String, dynamic>。以下字段名是 map 的键，不是 Dart 命名参数。String | int 表示 map 值可为其中任一类型；验证码有前导零时用 String。

下列公共字段由配置自动填入，传入同名 map 键可覆盖。各方法是否使用公共字段见下文。

map 键	类型	默认值
`grant_type`	`String`	`config.grantType`
`redirect_uri`	`String`	`config.redirectUri`
`scope`	`List<String>`	`config.scope`
`state`	`String`	`config.state`
`device_id`	`String`	无；SDK 不自动生成

结果 / 错误	字段及类型	说明
`AuthResponse<T>`	`data: T`、`message: String?`	成功结果。
`RootAuthException`	`message: String`、`statusCode: int?`、`errorCode: int?`	请求失败时抛出；网络超时 30 秒。
登录回调	`redirectUrl: String?`	普通登录不自动跳转或换 token；应用处理回调后调用 `setToken`。

4. 验证码与登录

sendCode(params: JsonMap) -> Future<AuthResponse<void>>：发送验证码。公共字段可选；其余 map 键如下：

键	类型	必填条件 / 用途
`type`	`String`	可选，默认 `EMAIL`；`EMAIL`、`PHONE_TEXT`、`WHATSAPP`。
`email`	`String`	`EMAIL` 时必填。
`email_template_type`	`String`	`EMAIL` 时必填；`register_code`、`login_code`、`reset_pass_code`、`login_mfa_code`。
`phone_code`、`phone_num`	`String`、`String`	`PHONE_TEXT` / `WHATSAPP` 时必填；区号不含 `+`。
`phone_text_template_type`	`String`	`PHONE_TEXT` 时必填；取值同邮件模板。
`mfa_token`	`String`	模板为 `login_mfa_code` 时必填。

login(params: JsonMap) -> Future<AuthResponse<LoginResult>>：type: String 必填；按类型传入：

`type`	必填的 map 键及类型
`EMAIL_PASS`	`email: String`、`password: String`
`EMAIL_CODE`	`email: String`、`code: String \| int`
`PHONE_PASS`	`phone_code: String`、`phone_num: String`、`password: String`
`PHONE_CODE`	`phone_code: String`、`phone_num: String`、`code: String \| int`
`USER_NAME_PASS`	`user_name: String`、`password: String`
`WHATSAPP_CODE`	`phone_code: String`、`phone_num: String`、`code: String \| int`

login

补充字段 / 结果	类型	说明
`is_invite`、`invite_auto_register`	`int`、`int`	可选，均为 0/1。
`password`	`String`	传明文；配置了 RSA 公钥时 SDK 自动加密。
`redirectUrl`	`String?`	成功回调地址。
`mfaToken`	`String?`	二次验证 token。
`mfaMethods`	`List<String>`	可选验证方式。
`requiresMfa`	`bool`	是否需要二次验证。

dart 复制代码

final result = await auth.login({
  'type': 'EMAIL_PASS',
  'email': 'user@example.com',
  'password': 'password',
});
if (result.data.requiresMfa) {
  // 用 result.data.mfaToken 调用 verifyLoginMfa。
} else {
  // 应用处理 result.data.redirectUrl。
}

verifyLoginMfa(params: JsonMap) -> Future<AuthResponse<JsonMap>>：完成二次验证。公共字段可选：

键	类型	必填条件
`mfa_token`	`String`	是，来自 `login`。
`mfa_type`	`String`	是：`EMAIL`、`EMAIL_BIND`、`PHONE_CODE`、`PHONE_CODE_BIND`、`TOTP`、`TOTP_BIND`。
`code`	`String \| int`	是，邮箱/短信/TOTP 验证码。
`email`	`String`	`EMAIL_BIND` 时。
`phone_code`、`phone_num`	`String`、`String`	`PHONE_CODE_BIND` 时。
`totp_bind_code`	`String \| int`	`TOTP_BIND` 要求先验证邮箱/手机号时。

返回的 data 是服务端原始 map，可能包含 redirect_url: String，由应用处理。

5. 注册与重置密码

register(params: JsonMap) -> Future<AuthResponse<JsonMap>>：type: String 可选，不传时按是否提供非空手机号字段选择邮箱或手机注册：

`type`	必填的 map 键及类型
`EMAIL_CODE_PASS`（默认）	`email: String`、`code: String \| int`、`password: String`
`PHONE_CODE_PASS`（手机号默认）	`phone_code: String`、`phone_num: String`、`code: String \| int`、`password: String`
`USER_NAME_PASS`	`user_name: String`、`password: String`
`WHATSAPP_CODE`	`phone_code: String`、`phone_num: String`、`code: String \| int`

公共字段可选。password 的 RSA 加密规则同 login；成功数据可能包含 redirect_url: String。

verifyResetPasswordCode(params: JsonMap) -> Future<AuthResponse<String>>：校验验证码，data 为 verify_token。此方法不自动加入公共字段。

键	类型	必填条件
`type`	`String`	是：`EMAIL_CODE` 或 `PHONE_CODE`。
`email`	`String`	`EMAIL_CODE` 时。
`phone_code`、`phone_num`	`String`、`String`	`PHONE_CODE` 时。
`code`	`String \| int`	是。

scene: String 由 SDK 固定为 reset_pass_code。

resetPassword(params: JsonMap) -> Future<AuthResponse<void>>：提交新密码。公共字段可选。

键	类型	必填条件
`type`	`String`	可选：`EMAIL_CODE` 或 `PHONE_CODE`；默认按手机号字段选择。
`email`	`String`	`EMAIL_CODE` 时。
`phone_code`、`phone_num`	`String`、`String`	`PHONE_CODE` 时。
`password`、`password_confirmation`	`String`、`String`	均必填；有 RSA 公钥时加密。
`code`	`String \| int`	未传 `verify_token` 时。
`verify_token`	`String`	未传 `code` 时；来自 `verifyResetPasswordCode`。

updateProfile(params: JsonMap) -> Future<AuthResponse<void>>：按需传入以下字段；不自动加入公共字段。

map 键	类型	用途
`user_name`	`String`	新用户名。
`password_old`	`String`	修改密码时的旧密码。
`password`	`String`	修改密码时的新密码。

有 RSA 公钥时，SDK 会加密两个密码字段。

6. 用户信息与第三方登录

getUserInfo(params: JsonMap) -> Future<AuthResponse<JsonMap>>：返回服务端原始 map。

map 键	类型	必填 / 默认值
`response_type`	`String`	必填；按服务端配置传入。
`redirect_uri`	`String`	可选；默认 `config.redirectUri`。
`scope`	`List<String>`	可选；默认 `config.scope`。
`state`	`String`	可选；默认 `config.state`。
`grant_type`	`String`	可选；默认 `config.grantType`。
`device_id`	`String`	可选；SDK 不自动生成。

方法	参数与类型	返回 / 行为
`signInWithGoogle({String? state})`	`state: String?` 可选，默认 `config.state`。	`Future<RootAuthAuthorizationGrant>`；Android 原生账号选择，不打开回调页。
`startThirdPartyLogin(String authBy, {JsonMap params = const {}})`	`authBy: String` 必填；`params: JsonMap` 可选，见下表。	`Future<Uri>`；Google 返回回调 URI，其他渠道打开浏览器并返回授权 URI。
`getThirdPartyQrAuthorize([JsonMap params = const {}])`	`params: JsonMap` 可选，见下表。	`Future<AuthResponse<JsonMap>>`；获取微信服务号二维码。
`getThirdPartyQrResult(String stateKey)`	`stateKey: String` 必填。	`Future<AuthResponse<JsonMap>>`；查询一次扫码状态。

接口	参数 / 字段及类型	说明
`signInWithGoogle`	`state: String?`	覆盖 `config.state`；iOS 抛 `UnsupportedError`。
`RootAuthAuthorizationGrant`	`code: String`、`state: String`、`callbackUri: Uri`	`code` 是授权码，由业务后端换取会话。
`startThirdPartyLogin`	`authBy: String`	如 `google_oauth`、`telegram`、`facebook`、`vkid`；依服务端配置。
`startThirdPartyLogin.params`	`JsonMap`	可传第 3 节公共字段；Google 可覆盖 `state: String`、`redirect_uri: String`；其他渠道的 `auth_by: String` 固定为 `authBy`，`response_type: String` 固定为 `code`。
`getThirdPartyQrAuthorize.params`	`JsonMap`	可传公共字段、`auth_by: String`；后者默认 `wechat_service`。
二维码授权结果 `data`	`qr_url: String?`、`authorize_url: String?`、`state_key: String \| int`、`expire_seconds: int?`	展示二维码，用 `state_key.toString()` 查询。
二维码查询结果 `data`	`status: String`、`redirect_url: String?`	应用负责轮询、过期和回调处理。

Google 原生登录需在同一 Google Cloud 项目配置 Web OAuth 客户端和应用包名、签名 SHA-1 对应的 Android OAuth 客户端；Web client ID 由服务端返回。

7. Token 与验证码

方法	参数与类型	返回 / 说明
`getAppConfig({bool refresh = false})`	`refresh: bool` 可选；`true` 强制刷新。	`Future<JsonMap>`；获取应用配置，默认缓存结果。
`getToken()`	无	`Future<String?>`；读取当前应用 token。
`setToken(String token)`	`token: String` 必填且非空。	`Future<void>`；保存业务后端取得的 access token。
`isAuthenticated()`	无	`Future<bool>`；仅判断本地 token 非空。
`logout()`	无	`Future<void>`；只清除本地 token。
`dispose()`	无	`void`；关闭 SDK 自建 HTTP 客户端。

扩展接口	参数及类型	返回 / 说明
`CaptchaHandler.verify`	`appConfig: JsonMap`、`captchaConfig: JsonMap`、`purpose: String`、`locale: String`，均必填	`Future<CaptchaTicket>`；`purpose` 为 `send-code` 或 `submit`。
`CaptchaTicket`	`ticket: String` 必填；`randStr: String?` 可选	每次请求使用新票据；`randStr` 用于腾讯验证码。
`TokenStore.read`	`key: String`	`Future<String?>`；读取 token。
`TokenStore.write`	`key: String`、`value: String`	`Future<void>`；保存 token。
`TokenStore.delete`	`key: String`	`Future<void>`；删除 token。
`GoogleIdentityProvider.signIn`	`serverClientId: String` 必填	`Future<String?>`；返回 Google ID token，取消时为 `null`。
`mapGoogleSignInException`	`error: GoogleSignInException`	返回 `RootAuthGoogleException`。
`mapGooglePlatformException`	`error: PlatformException`	返回 `RootAuthGoogleException`。
`RootAuthGoogleException.kind`	`GoogleAuthErrorKind`	`canceled`、`network`、`configuration`、`unavailable`、`inProgress`、`failed`。

规则	说明
验证码	开启后，`sendCode`、`login`、`register`、`verifyResetPasswordCode`、`resetPassword` 需要 `CaptchaHandler`。
Token 存储	默认 `SecureTokenStore([FlutterSecureStorage? storage])`；键名为 `rootauth.<appId>.accessToken`。
会话失效	HTTP 401 或业务错误码 1010 会清除本地 token。
HTTP 客户端	注入的客户端由应用关闭。

上一个

Web components 模式接入

下一个

后端接入

最近修改: 2026-10-29Powered by

大纲