# JVerify 极验验证插件文档

## 插件概述

`jverify` 是 OneApp 集成的极验验证 Flutter 插件，提供一键登录、短信验证等安全认证功能。该插件封装了极验验证的 Android 和 iOS SDK，为 Flutter 应用提供统一的验证接口。

### 基本信息
- **插件名称**: jverify
- **类型**: Flutter Plugin
- **平台支持**: Android, iOS
- **功能**: 一键登录、短信验证、SDK 初始化

## 目录结构

```
jverify/
├── lib/
│   └── jverify.dart              # Flutter 接口层
├── android/                      # Android 原生实现
│   ├── src/main/
│   │   ├── AndroidManifest.xml  # Android 清单文件
│   │   ├── java/                 # Java/Kotlin 源码
│   │   └── libs/                 # 第三方库文件
│   └── build.gradle             # Android 构建配置
├── ios/                          # iOS 原生实现
│   ├── Classes/                  # Objective-C/Swift 源码
│   ├── Assets/                   # iOS 资源文件
│   └── jverify.podspec          # CocoaPods 配置
├── documents/                    # 文档目录
├── pubspec.yaml                  # Flutter 插件配置
└── README.md                     # 项目说明
```

## Flutter 接口层 (lib/jverify.dart)

### 核心回调类型定义

#### 1. 事件监听器定义
```dart
// 自定义控件点击事件监听器
typedef JVClickWidgetEventListener = void Function(String widgetId);

// 授权页事件回调监听器
typedef JVAuthPageEventListener = void Function(JVAuthPageEvent event);

// 一键登录回调监听器
typedef JVLoginAuthCallBackListener = void Function(JVListenerEvent event);

// 短信登录回调监听器
typedef JVSMSListener = void Function(JVSMSEvent event);

// SDK 初始化回调监听器
typedef JVSDKSetupCallBackListener = void Function(JVSDKSetupEvent event);
```

#### 2. 事件数据模型
```dart
// 一键登录事件
class JVListenerEvent {
  final int code;        // 返回码：6000成功，6001失败
  final String message;  // 返回信息或loginToken
  final String operator; // 运营商：CM移动，CU联通，CT电信
}

// 短信验证事件
class JVSMSEvent {
  final int code;        // 返回码
  final String message;  // 返回信息
  final String phone;    // 手机号
}

// SDK 初始化事件
class JVSDKSetupEvent {
  final int code;        // 返回码：8000成功
  final String message;  // 返回信息
}

// 授权页事件
class JVAuthPageEvent {
  final String eventType; // 事件类型
  final Map<String, dynamic> data; // 事件数据
}
```

### 主要接口方法

#### 1. SDK 初始化
```dart
class Jverify {
  // 初始化 SDK
  static Future<void> setup({
    required String appKey,
    required String channel,
    bool isProduction = true,
    JVSDKSetupCallBackListener? setupListener,
  });
  
  // 检查初始化状态
  static Future<bool> isSetup();
}
```

#### 2. 一键登录
```dart
// 预初始化
static Future<void> preLogin({
  int timeOut = 5000,
  JVLoginAuthCallBackListener? preLoginListener,
});

// 判断网络环境是否支持
static Future<void> checkVerifyEnable({
  JVLoginAuthCallBackListener? checkListener,
});

// 获取登录 Token
static Future<void> loginAuth({
  bool autoDismiss = true,
  int timeOut = 5000,
  JVLoginAuthCallBackListener? loginListener,
});

// 自定义授权页面
static Future<void> setCustomAuthorizationView({
  required Map<String, dynamic> config,
  JVClickWidgetEventListener? clickListener,
  JVAuthPageEventListener? authPageEventListener,
});
```

#### 3. 短信验证
```dart
// 获取短信验证码
static Future<void> getSMSCode({
  required String phoneNumber,
  String? signID,
  String? tempID,
  JVSMSListener? smsListener,
});

// 短信验证登录
static Future<void> smsAuth({
  required String phoneNumber,
  required String smsCode,
  JVSMSListener? smsListener,
});
```

#### 4. 页面控制
```dart
// 关闭授权页面
static Future<void> dismissLoginAuth();

// 清除预取号缓存
static Future<void> clearPreLoginCache();

// 设置调试模式
static Future<void> setDebugMode(bool enable);
```

## Android 原生实现

### 项目结构
```
android/
├── src/main/
│   ├── AndroidManifest.xml      # 权限和组件配置
│   ├── java/com/jverify/        # Java 实现代码
│   │   ├── JverifyPlugin.java   # 插件主类
│   │   ├── JVerifyHelper.java   # 辅助工具类
│   │   └── utils/               # 工具类
│   └── libs/                    # 极验 SDK 库文件
│       ├── jverify-android-*.jar
│       └── jcore-android-*.jar
└── build.gradle                 # 构建配置
```

### 关键实现文件

#### 1. JverifyPlugin.java - 插件主类
```java
public class JverifyPlugin implements FlutterPlugin, MethodCallHandler {
    
    // 方法通道
    private MethodChannel channel;
    
    // 极验 SDK API 接口
    private JVerifyInterface jVerifyInterface;
    
    @Override
    public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
        channel = new MethodChannel(binding.getBinaryMessenger(), "jverify");
        channel.setMethodCallHandler(this);
    }
    
    @Override
    public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) {
        switch (call.method) {
            case "setup":
                initSDK(call, result);
                break;
            case "checkVerifyEnable":
                checkVerifyEnable(call, result);
                break;
            case "preLogin":
                preLogin(call, result);
                break;
            case "loginAuth":
                loginAuth(call, result);
                break;
            case "getSMSCode":
                getSMSCode(call, result);
                break;
            case "smsAuth":
                smsAuth(call, result);
                break;
            case "dismissLoginAuth":
                dismissLoginAuth(result);
                break;
            default:
                result.notImplemented();
        }
    }
}
```

#### 2. 核心功能实现
```java
// SDK 初始化
private void initSDK(MethodCall call, Result result) {
    String appKey = call.argument("appKey");
    String channel = call.argument("channel");
    boolean isProduction = call.argument("isProduction");
    
    JVerifyInterface.init(getApplicationContext(), appKey, channel, isProduction);
    JVerifyInterface.setDebugMode(true);
    
    // 设置初始化回调
    JVerifyInterface.setInitListener(new InitListener() {
        @Override
        public void onResult(int code, String message) {
            // 回调到 Flutter
            Map<String, Object> args = new HashMap<>();
            args.put("code", code);
            args.put("message", message);
            channel.invokeMethod("onSDKSetup", args);
        }
    });
}

// 一键登录
private void loginAuth(MethodCall call, Result result) {
    boolean autoDismiss = call.argument("autoDismiss");
    int timeOut = call.argument("timeOut");
    
    JVerifyInterface.loginAuth(getCurrentActivity(), autoDismiss, timeOut, 
        new LoginAuthListener() {
            @Override
            public void onResult(int code, String content, String operator) {
                Map<String, Object> args = new HashMap<>();
                args.put("code", code);
                args.put("message", content);
                args.put("operator", operator);
                channel.invokeMethod("onLoginAuth", args);
            }
        });
}
```

### Android 配置

#### AndroidManifest.xml 权限配置
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <!-- 电话权限 -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.SEND_SMS" />
    
    <!-- 其他权限 -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    
    <application>
        <!-- 极验服务配置 -->
        <meta-data
            android:name="JVERIFY_CHANNEL"
            android:value="${JVERIFY_CHANNEL}" />
        <meta-data
            android:name="JVERIFY_APPKEY"
            android:value="${JVERIFY_APPKEY}" />
    </application>
</manifest>
```

#### build.gradle 配置
```gradle
android {
    compileSdkVersion 33
    
    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 33
    }
    
    buildTypes {
        release {
            manifestPlaceholders = [
                JVERIFY_APPKEY: project.hasProperty('JVERIFY_APPKEY') ? JVERIFY_APPKEY : '',
                JVERIFY_CHANNEL: project.hasProperty('JVERIFY_CHANNEL') ? JVERIFY_CHANNEL : 'developer-default'
            ]
        }
    }
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.4.0'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}
```

## iOS 原生实现

### 项目结构
```
ios/
├── Classes/
│   ├── JverifyPlugin.h          # 插件头文件
│   ├── JverifyPlugin.m          # 插件实现文件
│   └── JVerifyHelper.h/m        # 辅助工具类
├── Assets/                      # 资源文件
├── Frameworks/                  # 极验 SDK 框架
│   └── JVERIFYService.framework
└── jverify.podspec             # CocoaPods 配置
```

### 关键实现文件

#### 1. JverifyPlugin.h - 插件头文件
```objc
#import <Flutter/Flutter.h>
#import <JVERIFYService/JVERIFYService.h>

@interface JverifyPlugin : NSObject<FlutterPlugin>

@property (nonatomic, strong) FlutterMethodChannel *channel;

@end
```

#### 2. JverifyPlugin.m - 插件实现
```objc
@implementation JverifyPlugin

+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar {
    FlutterMethodChannel* channel = [FlutterMethodChannel
        methodChannelWithName:@"jverify"
        binaryMessenger:[registrar messenger]];
    
    JverifyPlugin* instance = [[JverifyPlugin alloc] init];
    instance.channel = channel;
    [registrar addMethodCallDelegate:instance channel:channel];
}

- (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result {
    if ([@"setup" isEqualToString:call.method]) {
        [self initSDK:call result:result];
    } else if ([@"checkVerifyEnable" isEqualToString:call.method]) {
        [self checkVerifyEnable:call result:result];
    } else if ([@"preLogin" isEqualToString:call.method]) {
        [self preLogin:call result:result];
    } else if ([@"loginAuth" isEqualToString:call.method]) {
        [self loginAuth:call result:result];
    } else if ([@"getSMSCode" isEqualToString:call.method]) {
        [self getSMSCode:call result:result];
    } else if ([@"smsAuth" isEqualToString:call.method]) {
        [self smsAuth:call result:result];
    } else if ([@"dismissLoginAuth" isEqualToString:call.method]) {
        [self dismissLoginAuth:result];
    } else {
        result(FlutterMethodNotImplemented);
    }
}

// SDK 初始化
- (void)initSDK:(FlutterMethodCall*)call result:(FlutterResult)result {
    NSString *appKey = call.arguments[@"appKey"];
    NSString *channel = call.arguments[@"channel"];
    BOOL isProduction = [call.arguments[@"isProduction"] boolValue];
    
    [JVERIFYService setupWithAppkey:appKey channel:channel apsForProduction:isProduction];
    
    // 设置初始化回调
    [JVERIFYService setInitHandler:^(JVInitResultModel *result) {
        NSDictionary *args = @{
            @"code": @(result.code),
            @"message": result.message ?: @""
        };
        [self.channel invokeMethod:@"onSDKSetup" arguments:args];
    }];
    
    result(@(YES));
}

// 一键登录
- (void)loginAuth:(FlutterMethodCall*)call result:(FlutterResult)result {
    BOOL autoDismiss = [call.arguments[@"autoDismiss"] boolValue];
    NSTimeInterval timeOut = [call.arguments[@"timeOut"] doubleValue] / 1000.0;
    
    [JVERIFYService getAuthorizationWithController:[self getCurrentViewController]
                                          completion:^(JVAuthorizationResultModel *result) {
        NSDictionary *args = @{
            @"code": @(result.code),
            @"message": result.content ?: @"",
            @"operator": result.operator ?: @""
        };
        [self.channel invokeMethod:@"onLoginAuth" arguments:args];
    }];
    
    result(@(YES));
}

@end
```

### iOS 配置

#### jverify.podspec
```ruby
Pod::Spec.new do |s|
  s.name             = 'jverify'
  s.version          = '1.0.0'
  s.summary          = 'JVerify Flutter Plugin'
  s.description      = 'A Flutter plugin for JVerify SDK'
  s.homepage         = 'https://www.jiguang.cn'
  s.license          = { :file => '../LICENSE' }
  s.author           = { 'JiGuang' => 'support@jiguang.cn' }
  
  s.source           = { :path => '.' }
  s.source_files     = 'Classes/**/*'
  s.public_header_files = 'Classes/**/*.h'
  
  s.dependency 'Flutter'
  s.dependency 'JVerify', '~> 2.8.0'
  
  s.platform = :ios, '9.0'
  s.ios.deployment_target = '9.0'
  
  s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
  s.swift_version = '5.0'
end
```

#### Info.plist 配置
```xml
<dict>
    <!-- 应用传输安全设置 -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
    
    <!-- 网络使用说明 -->
    <key>NSPhotoLibraryUsageDescription</key>
    <string>此应用需要访问相册来选择头像</string>
    
    <!-- 电话权限说明 -->
    <key>NSContactsUsageDescription</key>
    <string>此应用需要访问通讯录进行一键登录</string>
</dict>
```

## 使用示例

### 基本集成
```dart
import 'package:jverify/jverify.dart';

class LoginPage extends StatefulWidget {
  @override
  _LoginPageState createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  
  @override
  void initState() {
    super.initState();
    _initJVerify();
  }
  
  // 初始化 JVerify SDK
  void _initJVerify() async {
    await Jverify.setup(
      appKey: "your_app_key",
      channel: "developer-default",
      isProduction: false,
      setupListener: (JVSDKSetupEvent event) {
        if (event.code == 8000) {
          print("SDK 初始化成功");
          _preLogin();
        } else {
          print("SDK 初始化失败: ${event.message}");
        }
      },
    );
  }
  
  // 预登录
  void _preLogin() async {
    await Jverify.preLogin(
      preLoginListener: (JVListenerEvent event) {
        if (event.code == 6000) {
          print("预登录成功");
        }
      },
    );
  }
  
  // 一键登录
  void _oneClickLogin() async {
    await Jverify.loginAuth(
      loginListener: (JVListenerEvent event) {
        if (event.code == 6000) {
          String loginToken = event.message;
          // 使用 loginToken 进行后续验证
          _verifyTokenWithServer(loginToken);
        } else {
          print("一键登录失败: ${event.message}");
        }
      },
    );
  }
  
  // 短信登录
  void _smsLogin(String phoneNumber, String smsCode) async {
    await Jverify.smsAuth(
      phoneNumber: phoneNumber,
      smsCode: smsCode,
      smsListener: (JVSMSEvent event) {
        if (event.code == 6000) {
          print("短信登录成功");
        }
      },
    );
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          ElevatedButton(
            onPressed: _oneClickLogin,
            child: Text("一键登录"),
          ),
          ElevatedButton(
            onPressed: () => _getSMSCode("13800138000"),
            child: Text("获取验证码"),
          ),
        ],
      ),
    );
  }
}
```

## 错误码说明

### 通用错误码
- **8000**: SDK 初始化成功
- **8001**: SDK 初始化失败
- **6000**: 登录获取 loginToken 成功
- **6001**: 登录获取 loginToken 失败
- **6002**: 网络连接失败
- **6003**: 请求超时
- **6004**: 运营商网络未知

### 一键登录错误码
- **6005**: 手机号不支持此运营商
- **6006**: 用户取消登录
- **6007**: 登录环境异常
- **6008**: 登录失败，未知异常

### 短信验证错误码
- **3000**: 短信验证码发送成功
- **3001**: 短信验证码发送失败
- **3002**: 短信验证码验证成功
- **3003**: 短信验证码验证失败

## 性能优化

### 网络优化
- 预登录机制减少用户等待时间
- 智能重试机制提高成功率
- 网络状态检测优化用户体验

### 内存优化
- 及时释放不用的资源
- 避免内存泄漏
- 合理管理生命周期

### 用户体验优化
- 自定义授权页面样式
- 加载状态指示
- 错误提示优化

## 安全特性

### 数据安全
- 通信数据加密传输
- 敏感信息本地加密存储
- 防止中间人攻击

### 业务安全
- 防刷机制
- 设备指纹验证
- 异常行为检测

## 测试指南

### 单元测试
- SDK 接口调用测试
- 错误处理测试
- 边界条件测试

### 集成测试
- 端到端登录流程测试
- 多平台兼容性测试
- 网络异常处理测试

### 性能测试
- 初始化耗时测试
- 内存使用测试
- 并发请求测试

## 故障排除

### 常见问题
1. **初始化失败**: 检查 AppKey 和渠道配置
2. **网络错误**: 检查网络权限和网络连接
3. **登录失败**: 检查运营商网络环境
4. **权限不足**: 检查必要权限的授权状态

### 调试技巧
- 开启调试模式查看详细日志
- 使用网络抓包工具分析请求
- 检查设备网络环境和运营商

## 版本更新

### 当前版本特性
- 支持三大运营商一键登录
- 支持短信验证码登录
- 支持自定义授权页面
- 完善的错误处理机制

### 后续规划
- 支持更多认证方式
- 优化用户体验
- 增强安全防护

## 总结

`jverify` 插件为 OneApp 提供了完整的极验验证解决方案，通过封装原生 SDK，为 Flutter 应用提供了统一、便捷的验证接口。插件具有良好的跨平台兼容性和完善的错误处理机制，能够满足移动应用的各种验证场景需求。