> >

概述及资源

行为验证 iOS SDK 提供给集成 iOS 原生客户端开发的开发者使用, SDK 不依赖任何第三方库。

环境需求

条目	资源
开发目标	兼容 iOS 9+
开发环境	Xcode 12+
系统依赖	`Webkit.framework`
sdk三方依赖	无

条目	资源
产品结构流程	通讯流程, 交互流程
SDK接口文档	gt3-ios-docs 或查看头文件注释
错误码列表	Error Code 列表

安装

获取SDK

使用极验行为验证 SDK 视为同意极验隐私政策

使用CocoaPods获取

在工程的Podfile文件中添加下面配置

pod 'GT3Captcha-iOS'

使用Swift Package Manager获取

详情请参考：https://github.com/GeeTeam/gt3-spm-repo

手动下载获取

使用从下方链接下载.zip文件获取最新的 SDK 及相关 Demo。

gt3-ios-sdk

导入SDK

如果您是手动添加 SDK , 将下载获取的GT3Captcha.framework文件拖拽到工程中, 确保Copy items if needed已被勾选。

请使用Linked Frameworks and Libraries方式导入framework。在拖入GT3Captcha.framework到工程时后, 还要检查.framework是否被添加到PROJECT -> Build Phases -> Linked Frameworks and Libraries。
针对静态库中的Category, 需要在对应target的Build Settings->Other Linker Flags添加-ObjC编译选项。如果依然有问题，再添加-all_load。
SDK 0.9.0 版本以后需要在工程中同时引入GT3Captcha.Bundle。把仓库中的 GT3Captcha.Bundle 拖入项目中. iOS7 不支持 Dynamic Library, 无法使用 embedded binaries。而 Dynamic Library 无法获取 .strings 等资源文件, 这里以 bundle 外嵌的方式单独管理 SDK 所需资源文件。

苹果在 WWDC23 上发布了应用程序（包括 SDK）的新隐私政策，并有 Get started with privacy manifests - WWDC23 - Videos - Apple Developer 的单独专题。7 月 27 日苹果发布了此则新闻，新闻称：2023 年秋季开始，如果新上传的应用程序中使用了没有提供隐私清单的相关 API，那么你将会收到一封邮件通知，而从 2024 年春季开始，隐私清单会变成一个强制要求。涉及到的 API 以及使用原因可参考：Describing use of required reason API | Apple Developer Documentation，如果使用原因未在列表中列出也可直接提交具体使用理由。
如何创建新隐私清单说明，可参考 Privacy manifest files | Apple Developer Documentation

行为验证 iOS SDK 使用了其中部分函数获取硬盘容量用于写入日志，涉及 NSPrivacyAccessedAPICategoryDiskSpace 特此说明.

配置接口

参考行为验证的通讯流程, 必须要先在您的后端搭建相应的服务端SDK，并配置从极验管理后台获取的id和key, 并且将配置的接口API1和API2放入客户端的初始化方法中。

集成用户需要使用iOS SDK完成提供的以下接口:

配置验证初始化
启动验证
获取验证结果
处理错误的代理

提供以下两种方式使用验证码:

直接通过GT3CaptchaManager与集成用户的事件绑定
通过极验的提供的GT3CaptchaButton(提供了默认样式)

此外, 无论使用何种方式集成, 都需要遵守<GTCaptchaManagerDelegate>协议以处理验证结果和可能返回的错误。

集成代码参考下方的代码示例

编译并运行你的工程

编译你的工程, 体验行为验证！

build

轻轻点击集成的验证按钮, 如此自然, 如此传神。

视觉展示

与集成用户自定义的按钮事件绑定方式集成
使用极验提供的独立按钮集成

代码示例

初始化与激活验证

在工程中的文件头部倒入验证动态库GT3Captcha.framework

#import <GT3Captcha/GT3Captcha.h>

使用自定义按钮事件绑定的方式集成

以在UIButton中集成为参考

初始化

初始化验证管理器GTCaptchaManager的实例, 在UIButton初始化方法中对GTCaptchaManager实例调用注册方法以获得注册数据:


- (GT3CaptchaManager *)manager {
    if (!_manager) {
        _manager = [[GT3CaptchaManager alloc] initWithAPI1:api_1 API2:api_2 timeout:5.0];
        _manager.delegate = self;
        
    }
    return _manager;
}

- (instancetype)initWithFrame:(CGRect)frame {
    self = [super initWithFrame:frame];
    
    if (self) {
        [self.manager registerCaptcha:nil];
    }
    return self;
}

激活验证

初始化和注册完成后, 调用下面的方法激活验证码:
[self.manager startGTCaptchaWithAnimated:YES];

使用 SDK 中的`GT3CaptchaButton`集成

以在ViewController中集成为参考

初始化

初始化验证管理器GTCaptchaManager的实例, 并将此实例传给验证按钮GTCaptchaButton, 然后将验证按钮添加到[ViewController view]上:

- (void)viewWillAppear:(BOOL)animated {
    [self createCaptcha];
}

- (void)createCaptcha {
    // 创建验证管理器实例
    GT3CaptchaManager *captchaManager = [[GT3CaptchaManager alloc] initWithAPI1:<--您的api1--> API2:<--您的api2--> timeout:5.0];
    captchaManager.delegate = self;
    
    //debug mode
//    [captchaManager enableDebugMode:YES];
    
    // 创建验证视图的实例, 并添加到父视图上
    GT3CaptchaButton *captchaButton = [[GT3CaptchaButton alloc] initWithFrame:CGRectMake(0, 0, 300, 44) captchaManager:captchaManager];
    captchaButton.center = self.view.center;
    // 推荐直接注册验证
    [captchaButton registerCaptcha:nil];
    [self.view addSubview:captchaButton];
}

激活验证

点击验证按钮或使用以下调用方式激活验证:
[captchaButton startCaptcha];

处理验证结果

只有完成二次验证后, 本次验证才是完整完成。您需要在遵守GTCaptchaManagerDelegate协议后, 处理以下代理方法:

- (void)gtCaptcha:(GT3CaptchaManager *)manager didReceiveSecondaryCaptchaData:(NSData *)data response:(NSURLResponse *)response error:(GT3Error *)error decisionHandler:(void (^)(GT3SecondaryCaptchaPolicy))decisionHandler {
    if (!error) {
        //处理你的验证结果
        NSLog(@"\nsession ID: %@,\ndata: %@", [manager getCookieValue:@"msid"], [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
        //成功请调用decisionHandler(GT3SecondaryCaptchaPolicyAllow)
        decisionHandler(GT3SecondaryCaptchaPolicyAllow);
        //失败请调用decisionHandler(GT3SecondaryCaptchaPolicyForbidden)
        //decisionHandler(GT3SecondaryCaptchaPolicyForbidden);
    }
    else {
        //二次验证发生错误
        decisionHandler(GT3SecondaryCaptchaPolicyForbidden);
        NSLog(@"validate error: %ld, %@", (long)error.code, error.localizedDescription);
    }
}

处理验证错误

验证过程中可能发生一些不可避免的错误, 您可以通过遵守GTCaptchaManagerDelegate协议后, 在下面的代理方法中进行处理:

- (void)gtCaptcha:(GTCaptchaManager *)manager errorHandler:(GTError *)error {
    //处理验证中返回的错误
    NSLog(@"error: %@", error.localizedDescription);
}

可能遇到的错误码请参考后面的列表: GT3Error

可选验证处理方法

修改 API1 请求

考虑到部分公司的服务是需要鉴权或者自定义参数的, 可以通过下面的代理方法来对API1请求实现自定义

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendRequestAPI1:(NSURLRequest *)originalRequest withReplacedHandler:(void (^)(NSURLRequest *))replacedHandler {
    NSMutableURLRequest *mRequest = [originalRequest mutableCopy];
    
    /**
     TO-DO, 处理mRequest, 进行自定义
     */
     
    replacedHandler(mRequest);
}

完全自定义 API1 和 API2 都可以参考示例工程下载内AsyncTaskButton文件。

自定义解析 API1 的数据

考虑到部分公司的业务接口响应格式是固定的或者使用前需要解密, 可以通过下面的代理方法来对 API1 的响应实现自定义解析，并将验证需要的参数返回

- (NSDictionary *)gtCaptcha:(GT3CaptchaManager *)manager didReceiveDataFromAPI1:(NSDictionary *)dictionary withError:(GT3Error *)error {
    // TO-DO
    // 自定义解析数据为管理器支持的数据格式
    NSString *gt = [dictionary objectForKey:@"gt"];
    NSString *challenge = [dictionary objectForKey:@"challenge"];
    NSNumber *success = [dictionary objectForKey:@"success"];
    
    // 检查 gt、challenge、success 三个字段是否存在
    if (gt && challenge && success) {
        NSDictionary *dict = [NSDictionary dictionaryWithObjectsAndKeys:gt, @"gt", challenge, @"challenge", success, @"success", nil];
        
        return dict;
    }
    
    return dictionary;
}

管理器支持的数据格式示例：

{
	"challenge" : "12ae1159ffdfcbbc306897e8d9bf6d06",
	"gt" : "ad872a4e1a51888967bdb7cb45589605",
	"success" : 1
}

本示例的详细参考见示例工程下载内的 RegisterViewController文件

完全自定义 API1 和 API2 都可以参考示例工程下载内AsyncTaskButton文件。

修改 API2 请求

考虑到部分公司的服务是需要鉴权或者自定义参数的, 可以通过下面的代理方法来对API1请求实现自定义

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendSecondaryCaptchaRequest:(NSURLRequest *)originalRequest withReplacedRequest:(void (^)(NSMutableURLRequest *))replacedRequest {
    /// 如果需要可以修改二次验证向服务器发送的请求
    NSMutableURLRequest *mReuqest = [originalRequest mutableCopy];
    NSData *secodaryData = mReuqest.HTTPBody;
    NSLog(@"data: %@", [[NSString alloc] initWithData:secodaryData encoding:NSUTF8StringEncoding]);
    
    /**
     TO-DO, 处理secodaryData, 添加业务数据
     */
     
//    NSData *newData = [secodaryData handlerYourData]
//    mReuqest.HTTPMethod = newData;
    replacedRequest(mReuqest);
}

完全自定义API1和API2都可以参考示例工程下载内 AsyncTaskButton 文件。

获取验证校验参数

如果需要记录验证返回的校验参数, 可以通过下面的代理方法来获取

- (void)gtCaptcha:(GT3CaptchaManager *)manager didReceiveCaptchaCode:(NSString *)code result:(NSDictionary *)result message:(NSString *)message {
    NSLog(@"result: %@", result);
}

禁用默认的 API1 请求

如果需要禁用 API1 请求, 可通过下面的方法进行修改

- (BOOL)shouldUseDefaultRegisterAPI:(GT3CaptchaManager *)manager {
    return NO;
}

因为API1请求被禁止, 需要手动配置验证的请求参数, 否则无法拉取验证, 示例如下:

// dict为包含gt、challenge、success的json字典
NSString *geetest_id = [dict objectForKey:@"gt"];
NSString *geetest_challenge = [dict objectForKey:@"challenge"];
NSNumber *geetest_success = [dict objectForKey:@"success"];
// 不要重复调用
[self.manager configureGTest:geetest_id challenge:geetest_challenge success:geetest_success withAPI2:api_2];

禁用默认API2请求

- (BOOL)shouldUseDefaultSecondaryValidate:(GT3CaptchaManager *)manager {
    return NO;
}

禁用默认的API2请求后, 验证结果的视图提示以代理方法gtCaptcha:didReceiveCaptchaCode:result:message:中返回的code为准, code 为 @"1"则进行成功结果提示。

可选的验证集成模式

考虑到 API1 及 API2 均为网站主自己的接口，而不同公司对接口的访问有不同的约定。 0.13.0 版本后，集成者可以根据 GT3AsyncTaskProtocol 协议创建含有自定义 API1 和 API2 的请求细节的对象，并通过 registerCaptchaWithCustomAsyncTask:completion: 将该对象注册进管理器。

使用该registerCaptchaWithCustomAsyncTask:completion: 进行定义 API1 和 API2 请求流程后，验证管理器不再访问以下代理方法:

shouldUseDefaultRegisterAPI:
gtCaptcha:willSendRequestAPI1:withReplacedHandler:
gtCaptcha:didReceiveDataFromAPI1:withError:
shouldUseDefaultSecondaryValidate:
gtCaptcha:willSendSecondaryCaptchaRequest:withReplacedRequest:

示例代码细节参考官方提供的 Demo 中 AsyncTaskButton.m 和 DemoAyncTask.m 文件。示例工程下载

其他接口及 Swift

详见官方的 SDK 接口文档

更多示例代码细节参考官方提供的 Demo，其中 Swift 示例代码请参考 Demo 源码中的 DefaultDemoViewController.swift 和 AsyncTaskViewController.swift 文件