概述及资源

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

环境需求

条目 资源
开发目标 兼容iOS7+
开发环境 Xcode 9.0
系统依赖 Webkit.framework, JavascriptCore.framework
sdk三方依赖

相关开发资源

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

安装

获取SDK

使用git命令从Github获取

git clone https://github.com/GeeTeam/gt3-ios-sdk.git

手动下载获取

使用从github下载.zip文件获取最新的sdk。

Github: gt3-ios-objc

导入SDK

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

    import

    请使用Linked Frameworks and Libraries方式导入framework。在拖入GT3Captcha.framework到工程时后, 还要检查.framework是否被添加到PROJECT -> Build Phases -> Linked Frameworks and Libraries

    linkedlibraries

  2. 针对静态库中的Category, 需要在对应target的Build Settings->Other Linker Flags添加-all_load编译选项。建议先添加-ObjC,如果依然有问题,再添加-all_load

    linkerflags

  3. SDK 0.9.0版本以后需要在工程中同时引入GT3Captcha.Bundle。把仓库中的 GT3Captcha.Bundle 拖入项目中. iOS7 不支持 Dynamic Library, 无法使用 embedded binaries。 而 Dynamic Library 无法获取 .strings 等资源文件, 这里以 bundle 外嵌的方式单独管理 SDK 所需资源文件。

配置接口

参考行为验证的产品结构流程, 必须要先在您的后端搭建相应的服务端SDK,并配置从极验管理后台获取的idkey, 并且将配置的接口API1API2放入客户端的初始化方法中。

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

  1. 配置验证初始化
  2. 启动验证
  3. 获取验证结果
  4. 处理错误的代理

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

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

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

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

编译并运行你的工程

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

build

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

视觉展示

  1. 与集成用户自定义的按钮事件绑定方式集成

    sample1

  2. 使用极验提供的独立按钮集成

    sample2

代码示例

初始化与激活验证

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

#import <GT3Captcha/GT3Captcha.h>

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

以在UIButton中集成为参考

  1. 初始化

    初始化验证管理器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;
    }
  1. 激活验证

    初始化和注册完成后, 调用下面的方法激活验证码:

    [self.manager startGTCaptchaWithAnimated:YES];

使用SDK中的GT3CaptchaButton集成

以在ViewController中集成为参考

  1. 初始化

    初始化验证管理器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];
    }
  1. 激活验证

    点击验证按钮或使用以下调用方式激活验证:

    [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);
}

修改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);
}

获取验证校验参数

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

- (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"则进行成功结果提示。

其他接口

详见API清单文档

示例代码细节参考官方提供的demo

详细演示demo