The official flutter plugin project for GeeTest Adaptive CAPTCHA. Support Flutter 2.0. 行为验 Flutter 官方插件。支持 Flutter 2.0。


安装 / Install

在工程 pubspec.yamldependencies 块中添加下列配置
Follow the steps below to set up dependencies in project pubspec.yaml

Github 集成 / Github integration

      ref: master

或 / or

pub 集成 / pub integration

  gt4_flutter_plugin: ^0.0.6

导入 SDK / Import SDK

注意:请将 SDK 导入到极验行为验 Flutter 插件的对应目录下,而非您项目的目录下

Please be advised: Import GeeTest CAPTCHA SDK to the according paths of GeeTest CAPTCHA Flutter plugin, other than your project's.

因为行为验原生 SDK 未提供远程依赖方式获取,需要手动下载和配置。在安装完 Flutter 插件后,需要手动从官网下载 AndroidiOS 的原生 SDK,并手动导入到相应的本地依赖路径:

Since GeeTest does not provide remote dependency integration methods for native SDKs currently, you will need to download and configure it manually. After installing the flutter plugin, please download the native Android and iOS SDK from from GeeTest dashboard. And then, import it to following paths:

/** Android Flutter 插件(Android Flutter plugin path) */

/** iOS Flutter 插件(iOS Flutter plugin path) */

注:使用flutter pub get下载插件成功后,Project>External Libraries>Flutter Plugins 中可以找到极验行为验 Flutter 插件的对应路径,上述插件路径即为此处。

Note: The path of GeeTest CAPTCHA Flutter plugin can be found in Project>External Libraries>Flutter Plugins after successful download using flutter pub get command. The plugin path above is here.

iOS 在插件对应路径导入SDK后,还需要在 Xcode 原生项目中导入资源文件GTCaptcha4.bundle, 否则集成后会报资源找不到的错误

If developing for iOS, you will need to import the resource file GTCaptcha4.bundle in the Xcode native project after importing the SDK into the corresponding path of the plugin, otherwise it will report an error that the resource cannot be found after integration

Android 在插件对应路径导入SDK后,还需要在插件的 android/build.gradle 文件中 dependencies 标签内添加 api(name:'geetest_captcha_android_vx.y.z_date', ext:'aar')

Android needs to add api(name:'geetest_captcha_android_vx.y.z_date', ext:'aar') inside the dependencies label in android/build.gradle file of the plugin after importing the SDK into the corresponding path of the plugin.

配置 / Configuration

请在 官网 申请验证 ID(captchaId)和 Key,并部署配套的后端接口。详细介绍请查阅:部署说明

Create your IDs and keys (GeeTest CAPTCHA V4) on GeeTest dashboard, and deploy the corresponding back-end API based on GeeTest documents.

示例 / Example


集成前,请先替换从后台申请的 captchaId(Please replace random captchaID in the below example with captchaID that you created from GeeTest dashboard before you process the integration. )

var config = GT4SessionConfiguration();
    config.language = "en";
    config.debugEnable = true;
    config.backgroundColor =;
    captcha =

config 说明 / config explanation

属性/attribute属性类型/attribute types属性说明/attribute explanation
resourcePathString静态资源文件的路径, 默认加载本地文件路径
Static resource file path is the load local file path by default. If ther is no special requirements, you don't need to configure it. You should set the full path for configurable remote files.
protocolString远程访问静态资源时的协议,默认 https
It is used for remote access to static resources. The default value is https
userInterfaceStyleGTC4UserInterfaceStyle界面样式,枚举 / Interface style, enumeration
system 跟随系统样式 / system style
light普通样式 / normal style
dark暗黑样式 / dark style
iOS 默认 light,Android默认system
iOS default interface is light, Android default interface is system
it is used for set background color, the default value is transparency.
Debugging mode switch, the default value is turn off
It is used for interaction of background clicking, the default value is on.
timeoutint请求超时时长,单位为毫秒,iOS 默认8000,Android 10000
Request timeout duration. The unit is milliseconds. The default value is 8000 for iOS and 10000 for Android
指定语言请参考文档中的语言短码清单(ISO 639-2 标准)
It is used for language setting, the default value is the same as system language.
The default language will be Chinese if your system language is not included in GeeTest multilingual setting.
Refer to the list of language short codes in the documentation (ISO 639-2) to specify the language.
additionalParameterMap<String,dynamic>额外的参数, 默认为空。参数将被组装后提交到验证服务
Additional parameters, null by default. The parameters will be assembled and submitted to the verification service.






captcha.addEventHandler(onShow: (Map<String, dynamic> message) async {
    // TO-DO
    // 验证视图已展示 the captcha view is displayed
    debugPrint("Captcha did show");
}, onResult: (Map<String, dynamic> message) async {
    debugPrint("Captcha result: " + message.toString());

    String status = message["status"];
    if (status == "1") {
        // TODO
        // 发送 message["result"] 中的数据向服务端二次查询接口查询结果 Send the data in the message ["result"] to query your API
        // 对结果进行二次校验 validate the result
        Map result = message["result"] as Map;

    } else {
        // 终端用户完成验证错误,自动重试 If the verification fails, it will be automatically retried.
        debugPrint("Captcha 'onResult' state: $status");
}, onError: (Map<String, dynamic> message) async {
    debugPrint("Captcha onError: " + message.toString());
    String code = message["code"];
    // TODO 处理验证中返回的错误 Handling errors returned in verification
    if (Platform.isAndroid) {
        // Android 平台
        if (code == "-14460") {
        // 验证会话已取消 The authentication session has been canceled
        } else {
        // 更多错误码参考开发文档 More error codes refer to the development document

    if (Platform.isIOS) {
        // iOS 平台
        if (code == "-20201") {
        // 验证请求超时 Verify request timeout
        else if (code == "-20200") {
        // 验证会话已取消 The authentication session has been canceled
        else {
        // 更多错误码参考开发文档 More error codes refer to the development document