GT3Captcha-iOS API Document

GT3Captcha.framework 主要包括GT3CaptchaButton, GT3CaptchaManager, GT3Error, GT3Utils 四个公有文件。

Protocol

GT3CaptchaButtonDelegate

captchaButtonShouldBeginCaptcha:

控制是否执行验证事件

Declaration

- (BOOL)captchaButtonShouldBeginCaptcha:(GT3CaptchaButton *)button;

Parameters

Param Description
button 验证按钮

Discussion

默认返回YES, 只有当返回NO时不执行验证事件

captchaButton:didChangeState:

验证状态改变的通知回调

Declaration

- (void)captchaButton:(GT3CaptchaButton *)button didChangeState:(GT3CaptchaState)state;

Parameters

Param Description
button 验证按钮
state 当前的按钮状态

GT3CaptchaManagerDelegate

gtCaptcha:errorHandler:

内部错误处理

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager errorHandler:(GT3Error *)error;

Parameters

Param Description
manager 验证管理器
error 错误对象

gtCaptcha:didReceiveSecondaryCaptchaData:response:error:decisionHandler:

通知已经收到二次验证结果, 并请在此处理最终验证结果

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager didReceiveSecondaryCaptchaData:(NSData *)data response:(NSURLResponse *)response error:(GT3Error *)error decisionHandler:(void (^)(GT3SecondaryCaptchaPolicy captchaPolicy))decisionHandler;

Parameters

Param Description
manager 验证管理器
data 二次验证返回的数据
response 二次验证的响应
error 错误对象
decisionHandler 更新验证结果的视图

shouldUseDefaultRegisterAPI:

将要向API1发送请求的时候调用此方法, 通过此方法可以修改将要发送的请求

Declaration

- (BOOL)shouldUseDefaultRegisterAPI:(GT3CaptchaManager *)manager;

Parameters

Param Description
manager 验证管理器

Discussion

调用此方法的时候必须调用requestHandler, 否则导致内存泄露

Return Value

返回是否使用默认的API1行为

gtCaptcha:willSendRequestAPI1:

将要向API1发送请求的时候调用此方法, 通过此方法可以修改将要发送的请求

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendRequestAPI1:(void (^)(NSURLRequest * request))requestHandler;

Parameters

Param Description
manager 验证管理器
requestHandler 修改请求的执行block

Discussion

调用此方法的时候必须调用requestHandler, 否则导致内存泄露

gtCaptcha:didReceiveDataFromAPI1:withError:

将要向API1发送请求的时候调用此方法, 通过此方法可以修改将要发送的请求

Declaration

- (NSDictionary *)gtCaptcha:(GT3CaptchaManager *)manager didReceiveDataFromAPI1:(NSDictionary *)dictionary withError:(GT3Error *)error;

Parameters

Param Description
manager 验证管理器
dictionary 包含极验的验证数据
error 返回的错误
  • 参数dictionary内数据样例
{
"challenge" : "12ae1159ffdfcbbc306897e8d9bf6d06",
"gt" : "ad872a4e1a51888967bdb7cb45589605",
"success" : 1
}

Return Value

返回自定解析后的challenge, gt, success数据, 结构参考上方样例

gtCaptcha:didReceiveCaptchaCode:result:message:

通知接收到返回的验证交互结果

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager didReceiveCaptchaCode:(NSString *)code result:(NSDictionary *)result message:(NSString *)message;

Parameters

Param Description
manager 验证管理器
code 验证交互结果
result 二次验证数据
message 附带消息

Discussion

此方法仅仅是前端返回的初步结果, 并非验证最终结果。获得result后还需进一步二次验证, 以校验数据是否伪造。

shouldUseDefaultSecondaryValidate:

将要向API2发送请求的时候调用此方法, 通过此方法可以修改将要发送的请求

Declaration

- (BOOL)shouldUseDefaultSecondaryValidate:(GT3CaptchaManager *)manager;

Parameters

Param Description
manager 验证管理器

Discussion

默认返回YES

Return Value

返回是否使用默认的API2行为

gtCaptcha:willSendSecondaryCaptchaRequest:

通知接收到返回的验证交互结果

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendSecondaryCaptchaRequest:(void (^)(NSMutableURLRequest * request))requestHandler;

Parameters

Param Description
manager 验证管理器
requestHandler 修改二次验证请求的block

Discussion

请不要修改requestHandler执行所在的线程或队列, 否则可能导请求修改失败. 二次验证的请求方式应为POST, 头部信息应为:

{"Content-Type":@"application/x-www-form-urlencoded;charset=UTF-8"}

gtCaptchaUserDidCloseGTView:

用户主动关闭了验证码界面

Declaration

- (void)gtCaptchaUserDidCloseGTView:(GT3CaptchaManager *)manager;

Parameters

Param Description
manager 验证管理器

GT3CaptchaManagerViewDelegate

gtCaptcha:notifyCaptchaMode:

通知验证模式

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager notifyCaptchaMode:(GT3CaptchaMode)mode;

Parameters

Param Description
manager 验证管理器
mode 验证模式

gtCaptchaWillShowGTView:

通知图形界面将要显示

Declaration

- (void)gtCaptchaWillShowGTView:(GT3CaptchaManager *)manager;

Parameters

Param Description
manager 验证管理器

gtCaptcha:updateCaptchaStatus:

更新验证状态

Declaration

- (void)gtCaptchaWillShowGTView:(GT3CaptchaManager *)manager;

Parameters

Param Description
manager 验证管理器
state 验证状态

gtCaptcha:updateCaptchaViewWithFactor:to:timeInterval:

更新验证视图

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager updateCaptchaViewWithFactor:(CGFloat)fromValue to:(CGFloat)toValue timeInterval:(NSTimeInterval)timeInterval;

Parameters

Param Description
manager 验证管理器
fromValue 起始值
toValue 终止值
timeInterval 时间间隔

GT3CaptchaManagerStatisticDelegate

略, 请阅读头文件注视

GT3CaptchaButton

极验提供的验证按钮, 继承于UIControl

Property

captchaManager

验证管理器

Declaration

@property (nonatomic, readonly, strong) GT3CaptchaManager *captchaManager;

Seealso

GT3CaptchaManager

delegate

验证按钮代理

Declaration

@property (nonatomic, weak) id<GT3CaptchaButtonDelegate> delegate;

captchaState

验证状态

Declaration

@property (nonatomic, readonly, assign) GT3CaptchaState captchaState;

captchaEdgeInsets

定义容器视图边距

Declaration

@property (nonatomic, assign) UIEdgeInsets captchaEdgeInsets;

tipsDict

定义各种验证状态下按钮上的提示文案

Declaration

@property (nonatomic, strong) NSDictionary<NSString *, NSAttributedString *> *tipsDict;

Discussion

字典请使用以下键名, 与GT3CaptchaState一一对应

'inactive', 'active', 'initial', 'waiting', 'collecting', 'computing', 'success', 'fail', 'error'.

Seealso

GT3CaptchaState

indicatorColor

定义验证状态指示器的颜色

Declaration

@property (nonatomic, strong) UIColor *indicatorColor;

logoImage

验证按钮上的logo图片

Declaration

@property (nonatomic, strong) UIImage *logoImage;

Method

initWithFrame:captchaManager:

初始化并返回一个新的规定了尺寸的GT3CaptchaButton实例对象

Declaration

- (instancetype)initWithFrame:(CGRect)frame captchaManager:(GT3CaptchaManager *)captchaManager;

Parameters

Param Description
frame 按钮的尺寸
captchaManager 验证管理器的实例

Return Value

一个新的规定了尺寸的GT3CaptchaButton实例对象

startCaptcha

开始验证

Declaration

- (void)startCaptcha;

Discussion

根据验证状态, 在GTCaptchaManager内部调用实例方法startGTCaptchaWithAnimated:, requestGTCaptcha, showGTViewIfRegiested

stopCaptcha

终止验证

Declaration

- (void)startCaptcha;

resetCaptcha

重置验证

Declaration

- (void)stopCaptcha;

updateTitleLabel:

立即更新当前的验证提示标题

Declaration

- (void)updateTitleLabel:(NSAttributedString *)title;

Parameters

Param Description
title 提示标题

GT3CaptchaManager

Property

delegate

验证管理的代理方法

Declaration

@property (nonatomic, weak) id<GT3CaptchaManagerDelegate> delegate;

viewDelegate

验证视图代理

Declaration

@property (nonatomic, weak) id<GT3CaptchaManagerViewDelegate> viewDelegate;

statisticDelegate

验证统计代理

Declaration

@property (nonatomic, weak) id<GT3CaptchaManagerStatisticDelegate> statisticDelegate;

captchaState

验证状态

Declaration

@property (nonatomic, readonly) GT3CaptchaState captchaState;

isShowing

图形验证的展示状态

Declaration

@property (nonatomic, readonly) BOOL isShowing;

API_1

获取启动验证参数的接口

Declaration

@property (nonatomic, readonly) NSURL *API_1;

API_2

进行二次验证的接口

Declaration

@property (nonatomic, readonly) NSURL *API_2;

gt_captcha_id

本次验证会话的验证ID

Declaration

@property (nonatomic, readonly, strong) NSString *gt_captcha_id;

gt_challenge

本次验证的会话的流水号

Declaration

@property (nonatomic, readonly, strong) NSString *gt_challenge;

gt_success_code

当前验证的服务状态

Declaration

@property (nonatomic, readonly, strong) NSNumber *gt_success_code;

Discussion

1正常/0宕机

maskColor

验证背景颜色

Declaration

@property (nonatomic, strong) UIColor *maskColor;

Method

sdkVersion

SDK版本号

Declaration

+ (NSString *)sdkVersion;

sharedGTManager

验证单例

Declaration

+ (instancetype)sharedGTManager;

initWithAPI1:API2:timeout:

验证初始化方法

Declaration

- (instancetype)initWithAPI1:(NSString *)api_1
API2:(NSString *)api_2
timeout:(NSTimeInterval)timeout NS_DESIGNATED_INITIALIZER;

Parameters

Param Description
api_1 获取验证参数的接口
api_2 进行二次验证的接口
timeout 超时时长

Return Value

一个新的GT3CaptchaManager实例

Discussion

NS_DESIGNATED_INITIALIZER, 请不要使用init

cancelRequest

取消异步请求

Declaration

- (void)cancelRequest;

Discussion

当希望取消正在执行的NSURLSessionDataTask时,调用此方法

configureGTest:challenge:success:withAPI2:

自定义配置验证方法

Declaration

- (void)configureGTest:(NSString *)gt_public_key
challenge:(NSString *)gt_challenge
success:(NSNumber *)gt_success_code
withAPI2:(NSString *)api_2;

Parameters

Param Description
gt_public_key 自定义时需要实现的动画block,仅在type配置为GTIndicatorCustomType时才执行
gt_challenge 状态指示器的类型
gt_success_code 网站主服务器监测geetest服务的可用状态, 0/1 不可用/可用
api_2 用于二次验证的接口.网站主根据极验服务端sdk来部署

Discussion

同一个challenge只能使用在同一次验证会话中

registerCaptcha:

注册验证

Declaration

- (void)registerCaptcha:(GT3CaptchaDefaultBlock)completionHandler;

Parameters

Param Description
completionHandler 注册完成的回调

Discussion

必须在startGTCaptchaWithAnimated:前调用

Seealso

GT3CaptchaDefaultBlock

startGTCaptchaWithAnimated:

开始验证

Declaration

- (void)startGTCaptchaWithAnimated:(BOOL)animated;

Parameters

Param Description
animated 控制验证视图弹出动画的启动

Discussion

获取姿态, 提交分析后, 如有必要在keyWindow上创建极验验证的GTView验证视图

极验验证GTWebView通过JS与SDK通信

stopGTCaptcha

终止验证

Declaration

- (void)stopGTCaptcha;

resetGTCaptcha

重置验证

Declaration

- (void)resetGTCaptcha;

Discussion

内部实现是先调用stopGTCaptcha, 在主线程延迟0.3秒后, 执行startCaptcha方法, 且只有在captchaStateGT3CaptchaStateFail,GT3CaptchaStateError,
GT3CaptchaStateSuccess, GT3CaptchaStateCancel才会有效。

执行完后, 状态为GT3CaptchaStateInit

closeGTViewIfIsOpen

若验证显示则关闭验证界面

Declaration

- (void)closeGTViewIfIsOpen;

getCookieValue:

获取cookie value

Declaration

- (NSString *)getCookieValue:(NSString *)cookieName;

Parameters

Param Description
cookieName cookie的键名

Discussion

获取姿态, 提交分析后, 如有必要在keyWindow上创建极验验证的GTView验证视图

Return Value

返回cookie value

useGTViewWithTimeout:

配置GTView资源请求超时时长

Declaration

- (void)useGTViewWithTimeout:(NSTimeInterval)timeout;

Parameters

Param Description
timeout 超时时长

useGTViewWithTitle:

验证标题

Discussion

默认不开启. 字符长度不能超过28, 一个中文字符为两个2字符长度.

Declaration

- (void)useGTViewWithTitle:(NSString *)title;

Parameters

Param Description
title 验证标题字符串

useAnimatedAcitvityIndicator:withIndicatorType:

验证视图高度约束

Declaration

- (void)useAnimatedAcitvityIndicator:(GT3IndicatorAnimationViewBlock)animationBlock
withIndicatorType:(GT3ActivityIndicatorType)type

Parameters

Param Description
animationBlock 动画执行的block
type 状态指示器类型

Discussion

为了能方便的调试动画,真机调试模拟低速网络, Settings->Developer->Status->Enable->Edge(😂)

useVisualViewWithEffect:

配置背景模糊

Declaration

- (void)useVisualViewWithEffect:(UIBlurEffect *)blurEffect;

Parameters

Param Description
blurEffect 模糊效果

Discussion

iOS8以上生效

useLanguage:

切换验证语言

Declaration

- (void)disableSecurityAuthentication:(BOOL)disable;

Parameters

Param Description
Type 语言类型

Discussion

默认开启HTTPS

disableSecurityAuthentication:

控制使用HTTPS协议请求验证

Declaration

- (void)disableSecurityAuthentication:(BOOL)disable;

Parameters

Param Description
disable 是否禁止https支持

Discussion

默认开启HTTPS

disableBackgroundUserInteraction:

控制验证背景交互事件

Declaration

- (void)disableBackgroundUserInteraction:(BOOL)disable;

Parameters

Param Description
disable 控制背景的点击交互事件

Discussion

默认不禁止

enableNetworkReachability:

控制内部的网络可达性检测

Declaration

- (void)enableNetworkReachability:(BOOL)enable;

Parameters

Param Description
enable 默认不禁止

Discussion

默认不禁止

enableDebugMode:

Debug Mode

Declaration

- (void)enableDebugMode:(BOOL)enable;

Parameters

Param Description
disable 控制debug模式

Discussion

默认不开启

GT3Error

极验封装的错误对象, 用于方便构造和返回特别信息

GT3ErrorType

极验定义的错误类型

Declaration

typedef NS_ENUM(NSUInteger, GT3ErrorType) {
/** 用户中断验证导致 */
GT3ErrorTypeUser,
/** 服务端返回错误 */
GT3ErrorTypeServer,
/** 内部网络抛出错误类型 */
GT3ErrorTypeNetWorking,
/** 内部浏览器抛出的错误类型 */
GT3ErrorTypeWebView,
/** 从前端库抛出的错误类型 */
GT3ErrorTypeJavaScript,
/** 内部解码错误类型 */
GT3ErrorTypeDecode,
/** 未知错误类型 */
GT3ErrorTypeUnknown
};

GT3Error Code

业务错误代码

test-Button产品的业务错误代码

ErrorCode Description
-10 验证被封禁
-20 尝试过多
-30 验证配置, 传入的参数不合法或为空, challenge只能使用一次
-40 配置问题, 传入的参数不合法或为空
-50 极验服务器响应异常, gettype.php
-51 极验服务器响应异常, get.php
-52 极验服务器响应异常, ajax.php
-70 接口调用错误, 未配置参数或设置代理方法
-71 缺失GT3Captcha.bundle文件
-80 接口调用错误, 未设置GT3CaptcaManagerDelegate代理方法

Cocoa Error

可能遇见的有

NSURLErrorDomain

ErrorCode Description
-999 NSURLErrorCancelled用户操作导致的请求中断, 一般忽略处理
-1000 NSURLErrorBadURLURL异常
-1001 NSURLErrorTimedOut请求超时
-1002 NSURLErrorUnsupportedURL不支持的URL
-1003 NSURLErrorCannotFindHost无法找到主机
-1004 NSURLErrorCannotConnectToHost无法连接到服务器
-1005 NSURLErrorNetworkConnectionLost网络丢失, 一般弱网或者网络突然中断导致
-1006 NSURLErrorDNSLookupFailedDNS查询失败
-1007 NSURLErrorHTTPTooManyRedirects过多的请求跳转, 服务器返回过多的302
-1008 NSURLErrorResourceUnavailable访问的资源不可用
-1009 NSURLErrorNotConnectedToInternet未连接到互联网
-1010 NSURLErrorRedirectToNonExistentLocation重定向到不存在的地址
-1011 NSURLErrorBadServerResponse服务器无响应
-1012 NSURLErrorUserCancelledAuthentication客户端取消了安全认证, 或者证书不匹配或服务端不支持ssl和tls
-1013 NSURLErrorUserAuthenticationRequired客户端要求安全认证, 服务端不支持ssl或tls
-1014 NSURLErrorZeroByteResource返回字节流为空
-1015 NSURLErrorCannotDecodeRawData无法解析的原始数据
-1016 NSURLErrorCannotDecodeContentData解析返回内容错误
-1017 NSURLErrorCannotParseResponse无法解析响应体
-1102 NSURLErrorNoPermissionsToReadFile无资源访问权限, 一般为challenge等参数有误, challenge只可被用来请求一次, 失效后可能会遇到该问题
-1200 NSURLErrorSecureConnectionFailed创建安全连接失败
-1201 NSURLErrorServerCertificateHasBadDate服务端证书异常
-1202 NSURLErrorServerCertificateUntrusted服务端证书不可信
-1203 NSURLErrorServerCertificateHasUnknownRoot服务端使用未知的根证书

Other

ErrorCode Description
3840 JSON解析故障, 请检查返回的是否为合法的JSON格式

更多详情请访问URL Loading System Error Codes文档及相关苹果官方文档

Property

metaData

发生错误时接收到的元数据, 没有数据则为nil

Declaration

@property (nonatomic, readonly, strong) NSData * _Nullable metaData;

gtDescription

极验的额外错误信息

Declaration

@property (nonatomic, readonly, strong) NSString * gtDescription;

originalError

原始的error

Declaration

@property (nonatomic, readonly, strong) NSError * _Nullable originalError;

Method

errorWithDomainType:code:userInfo:withGTDesciption:

通过提供的详细的参数初始化GT3Error

Declaration

+ (instancetype)errorWithDomainType:(GT3ErrorType)type code:(NSInteger)code userInfo:(nullable NSDictionary *)dict withGTDesciption:(NSString *)description;

Parameters

Param Description
type 极验定义的错误类型
code 错误码
dict 错误的userInfo
description 错误的额外描述字段

errorWithDomainType:originalError:withGTDesciption:

基于提供的NSError封装成GT3Error

Declaration

+ (instancetype)errorWithDomainType:(GT3ErrorType)type originalError:(NSError *)originalError withGTDesciption:(NSString *)description;

Parameters

Param Description
type 极验定义的错误类型
error 原始的NSError实例对象
description 错误的额外描述字段

GT3Utils

极验验证工具类

GT3CaptchaState

极验验证状态的枚举量

Declaration

typedef NS_ENUM(NSInteger, GT3CaptchaState) {
/** 验证未激活 */
GT3CaptchaStateInactive,
/** 验证激活 */
GT3CaptchaStateActive,
/** 验证初始化中 */
GT3CaptchaStateInitial,
/** 验证检测数据中 */
GT3CaptchaStateCollecting,
/** 验证等待提交中 */
GT3CaptchaStateWaiting,
/** 验证结果判定中*/
GT3CaptchaStateComputing,
/** 验证通过*/
GT3CaptchaStateSuccess,
/** 验证失败*/
GT3CaptchaStateFail,
/** 验证发生错误*/
GT3CaptchaStateError
};

GT3CaptchaMode

验证模式枚举量

Declaration

typedef NS_ENUM(NSInteger, GT3CaptchaMode) {
/** 验证默认模式*/
GT3CaptchaModeDefault,
/** 验证宕机模式*/
GT3CaptchaModeFailback
};

GT3SecondaryCaptchaPolicy

视图上结果的更新策略

Declaration

typedef NS_ENUM(NSInteger, GT3SecondaryCaptchaPolicy) {
/** 二次验证通过 */
GT3SecondaryCaptchaPolicyAllow,
/** 二次验证拒绝 */
GT3SecondaryCaptchaPolicyForbidden
};

GT3LanguageType

语言选项

Declaration

typedef NS_ENUM(NSInteger, GT3LanguageType) {
/** Simplified Chinese */
GT3LANGTYPE_ZH_CN = 0,
/** Traditional Chinese */
GT3LANGTYPE_ZH_TW,
/** Traditional Chinese */
GT3LANGTYPE_ZH_HK,
/** Korean */
GT3LANGTYPE_KO_KR,
/** Japenese */
GT3LANGTYPE_JA_JP,
/** English */
GT3LANGTYPE_EN_US,
/** System language*/
GT3LANGTYPE_AUTO
};

GT3ActivityIndicatorType

活动指示器类型

Declaration

typedef NS_ENUM(NSInteger, GT3ActivityIndicatorType) {
/** System Indicator Type */
GT3IndicatorTypeSystem = 0,
/** Geetest Defualt Indicator Type */
GT3IndicatorTypeDefault,
/** Custom Indicator Type */
GT3IndicatorTypeCustom,
};

Parameters

Param Description
code 验证结果
result 二次验证的数据
message 其他消息

GT3CaptchaDefaultBlock

验证默认回调

Declaration

typedef void(^GT3CaptchaDefaultBlock)(void);

GT3IndicatorAnimationViewBlock

自定义状态指示器的动画实现block

Declaration

typedef void(^GT3IndicatorAnimationViewBlock)(CALayer *layer, CGSize size, UIColor *color);

Parameters

Param Description
layer 状态指示器视图的layer
size layer的大小,默认 {64, 64}
color layer的颜色,默认 蓝色 [UIColor colorWithRed:0.3 green:0.6 blue:0.9 alpha:1]