Captcha v4
部署文档

iOS 集成

iOS 原生应用集成指南

环境要求

项目要求
开发目标iOS 9.0+
开发环境Xcode 13.0+
系统依赖Webkit.framework
第三方依赖无

SDK 已提供 XCFramework 格式，支持真机和模拟器。

安装

导入 XCFramework

将下载获取的 GeeLabCaptcha.xcframework 文件拖拽到工程中，确保 Copy items if needed 已被勾选。

使用 Linked Frameworks and Libraries 方式导入 framework。在拖入后，检查 .framework 文件是否被添加到 PROJECT -> Build Phases -> Linked Frameworks and Libraries。

配置 Linker Flags

针对静态库中的 Category，需要在对应 target 的 Build Settings -> Other Linker Flags 添加 -ObjC。

导入资源包

将 SDK 路径下的 GeeLabCaptcha.Bundle 拖入项目中。

重要： 必须导入 GeeLabCaptcha.Bundle，否则验证码无法正常工作。

隐私清单说明

从 2024 年春季开始，苹果要求所有应用和 SDK 提供隐私清单。

行为验证 iOS SDK 使用了以下 API 类别用于风控目的：

  • NSPrivacyAccessedAPICategoryDiskSpace - 获取硬盘容量信息
  • NSPrivacyAccessedAPICategoryFileTimestamp - 环境检测信息

参考文档：

基础集成

导入头文件

ViewController.m
#import <GeeLabCaptcha/GeeLabCaptcha.h>

初始化验证会话

ViewController.m
#define captchaID @"YOUR_CAPTCHA_ID"

@interface ViewController () <GeeLabCaptchaSessionTaskDelegate>

@property (strong, nonatomic) IBOutlet UIButton *startBtn;
@property (nonatomic, strong) GeeLabCaptchaSession *captchaSession;

@end

@implementation ViewController

- (GeeLabCaptchaSession *)captchaSession {
    if (!_captchaSession) {
        _captchaSession = [GeeLabCaptchaSession sessionWithCaptchaID:captchaID];
        _captchaSession.delegate = self;
    }
    return _captchaSession;
}

- (void)viewDidLoad {
    [super viewDidLoad];

    // 提前初始化验证会话（推荐）
    [self captchaSession];

    [self.startBtn addTarget:self
                      action:@selector(start)
            forControlEvents:UIControlEventTouchUpInside];
}

- (void)start {
    [self.captchaSession verify];
}

@end

提前初始化验证会话可以提升用户体验，减少等待时间。

导入框架

ViewController.swift
import GeeLabCaptcha

初始化验证会话

ViewController.swift
class ViewController: UIViewController {
    private let captchaID = "YOUR_CAPTCHA_ID"
    private var captchaSession: GeeLabCaptchaSession?

    override func viewDidLoad() {
        super.viewDidLoad()

        // 初始化验证会话
        captchaSession = GeeLabCaptchaSession(captchaID: captchaID)
        captchaSession?.delegate = self
    }

    @IBAction func startVerification(_ sender: UIButton) {
        captchaSession?.verify()
    }
}

extension ViewController: GeeLabCaptchaSessionTaskDelegate {
    // 实现代理方法
}

更多 Swift 示例代码请参考官方 Demo 中的 DefaultDemoViewController.swift 文件。

配置选项

自定义配置

通过 GeeLabCaptchaSessionConfiguration 自定义验证行为：

自定义配置示例
GeeLabCaptchaSessionConfiguration *config = [GeeLabCaptchaSessionConfiguration defaultConfiguration];

// 设置超时时间（秒）
config.timeout = 8.0f;

// 设置语言
config.language = @"zh-cn";

// 设置额外参数
config.additionalParameter = @{
    @"hideSuccess": @(1),  // 隐藏成功提示
    @"loading": @""        // 自定义 loading
};

// 使用自定义配置创建会话
_captchaSession = [GeeLabCaptchaSession sessionWithCaptchaID:captchaID
                                              configuration:config];

配置参数说明

参数类型说明
timeoutNSTimeInterval超时时间（秒）
languageNSString语言代码（如 zh-cn, en）
additionalParameterNSDictionary额外参数
resourcePathNSString自定义资源路径

处理验证结果

实现 GeeLabCaptchaSessionTaskDelegate 协议处理验证结果：

处理验证成功
- (void)geelabCaptchaSession:(GeeLabCaptchaSession *)captchaSession
                  didReceive:(NSString *)code
                      result:(NSDictionary *)result {
    NSLog(@"result: %@", result);

    // code 为 @"1" 表示用户完成验证
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // 构造表单数据
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id key, id obj, BOOL *stop) {
                if ([key isKindOfClass:[NSString class]] &&
                    [obj isKindOfClass:[NSString class]]) {
                    NSString *kvPair = [NSString stringWithFormat:@"%@=%@", key, obj];
                    [kvPairs addObject:kvPair];
                }
            }];

            NSString *formStr = [kvPairs componentsJoinedByString:@"&"];
            NSData *data = [formStr dataUsingEncoding:NSUTF8StringEncoding];

            // 提交到后端验证
            NSURL *url = [NSURL URLWithString:@"https://your-api.com/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod = @"POST";
            request.HTTPBody = data;

            [[[NSURLSession sharedSession] dataTaskWithRequest:request
                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                if (!error && data) {
                    NSString *msg = [[NSString alloc] initWithData:data
                                                          encoding:NSUTF8StringEncoding];
                    NSLog(@"验证结果: %@", msg);
                } else {
                    NSLog(@"验证错误: %@", error);
                }
            }] resume];
        }
    }
}

重要： 必须在服务端进行二次验证，不要仅依赖客户端结果。

处理验证错误
- (void)geelabCaptchaSession:(GeeLabCaptchaSession *)captchaSession
              didReceiveError:(GeeLabCaptchaError *)error {
    // 向用户展示错误信息和错误码
    NSString *message = [NSString stringWithFormat:@"验证错误 [%@]: %@",
                        error.code, error.description];

    UIAlertController *alert = [UIAlertController
        alertControllerWithTitle:@"验证失败"
        message:message
        preferredStyle:UIAlertControllerStyleAlert];

    [alert addAction:[UIAlertAction actionWithTitle:@"确定"
                                              style:UIAlertActionStyleDefault
                                            handler:nil]];

    [self presentViewController:alert animated:YES completion:nil];

    // 记录错误日志
    NSLog(@"验证错误详情: %@", error.description);
}

强烈建议在向用户展示验证错误时，同时展示错误码，方便后续排查线上问题。

常见问题

下一步

Web 集成

Web 和 H5 应用集成指南

Android 集成

Android 原生应用集成指南

On this page

环境要求安装导入 XCFramework配置 Linker Flags导入资源包隐私清单说明基础集成导入头文件初始化验证会话导入框架初始化验证会话配置选项自定义配置配置参数说明处理验证结果常见问题下一步