Protocol

GT3CaptchaButtonDelegate

captchaButtonShouldBeginCaptcha:

Ask delegate if verification should begin.

Declaration

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

Parameters

Param Description
button captcha button

Returns

YES means verification should begin or NO means it should not. The default is YES.

captchaButton:didChangeState:

Called if GT3CaptchaState (i.e. verification status) changed.

Declaration

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

Parameters

Param Description
button captcha button
state Current status of captcha button

GT3CaptchaManagerDelegate

gtCaptcha:errorHandler:

Handle internal error

Declaration

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

Parameters

Param Description
manager captcha manager
error Error object

gtCaptcha:didReceiveSecondaryCaptchaData:response:error:decisionHandler:

Notify after the captcha manager finished the secondary verification. Please handle the final result of verification.

Declaration

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

Parameters

Param Description
manager captcha manager
data The returned data of secondary verification
response The response of secondary verification
error Error object
decisionHandler A block to be called when your captcha manager has decided to allow or forbidden. The block takes a single parameter, which must be one of the constants of the enumerated type GT3SecondaryCaptchaPolicy.

shouldUseDefaultRegisterAPI:

Ask delegate if manager should use default register API1 logic.

Declaration

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

Parameters

Param Description
manager captcha manager

Return Value

YES if the manager should use default register API1 logic or NO it it should not. The default is YES.

gtCaptcha:willSendRequestAPI1:withReplacedHandler:

Modify the API1 request before sent it.

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendRequestAPI1:(NSURLRequest *)originalRequest withReplacedHandler:(void (^)(NSURLRequest * request))replacedHandler;

Parameters

Param Description
manager captcha manager
requestHandler A block to be called when your API1 request has been replaced. The block takes a single parameter, which must be a kind of NSURLRequest

gtCaptcha:didReceiveDataFromAPI1:withError:

Get the response of API1 request. You can customize your response depend on the requirements.

Declaration

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

Parameters

Param Description
manager captcha manager
dictionary Include verification parameters to start captcha
error Returned error
  • The following is a data structure example of dictionary
{
"challenge" : "12ae1159ffdfcbbc306897e8d9bf6d06",
"gt" : "ad872a4e1a51888967bdb7cb45589605",
"success" : 1
}

Return Value
Please return the challenge, gt and success in the same data structure with the example above.

gtCaptcha:didReceiveCaptchaCode:result:message:

Get the parameters for secondary verification

Declaration

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

Parameters

Param Description
manager captcha manager
code the indicator of result. @”1” if user passed the captcha test or @”0” if not.
result parameters for secondary verification
message Additional message

Discussion

The result returned by this method is NOT the final verification result. There is a secondary verification to validate the data after you have got the result.

shouldUseDefaultSecondaryValidate:

Ask delegate if manager should use default secondary verification logic.

Declaration

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

Parameters

Param Description
manager captcha manager

Return Value
YES if the manager should use default secondary verification logic or NO it it should not. The default is YES.

gtCaptcha:willSendSecondaryCaptchaRequest:withReplacedRequest:

Modify the API2 request before sent it.

Declaration

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendSecondaryCaptchaRequest:(NSURLRequest *)originalRequest withReplacedRequest:(void (^)(NSMutableURLRequest * request))replacedRequest

Parameters

Param Description
manager captcha manager
requestHandler A block to be called when your API2 request has been replaced. The block takes a single parameter, which must be a kind of NSURLRequest

Discussion

Please do not use child thread. The following is an example of header of the request.

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

gtCaptchaUserDidCloseGTView:

Notify if user has closed the captcha challenge manually

Declaration

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

Parameters

Param Description
manager captcha manager

GT3CaptchaManagerViewDelegate

gtCaptcha:notifyCaptchaMode:

Notify if captcha mode changed.
Declaration

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

Parameters

Param Description
manager captcha manager
mode captcha mode

gtCaptchaWillShowGTView:

Notify captcha challenge will pop out

Declaration

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

Parameters

Param Description
manager captcha manager

gtCaptcha:updateCaptchaStatus:

Notify if the verification status updates

Declaration

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

Parameters

Param Description
manager captcha manager
state Verification status

GT3CaptchaButton

Captcha button inherited UIControl

Property

captchaManager

Captcha manager

Declaration

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

Seealso

GT3CaptchaManager

delegate

Captcha button delegate

Declaration

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

captchaState

Verification status

Declaration

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

captchaEdgeInsets

Define the insets of captcha button

Declaration

@property (nonatomic, assign) UIEdgeInsets captchaEdgeInsets;

tipsDict

Use these keys to config title label in different state of the captcha button

Declaration

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

Discussion

Please use the following key, in order to be corresponding with GT3CaptchaState, including

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

Seealso

GT3CaptchaState

mainColor

The background color of captcha button.

Declaration

@property (nonatomic, strong) UIColor *mainColor;

indicatorColor

Define color for captcha indicator (i.e. the radar in the captcha button)

Declaration

@property (nonatomic, strong) UIColor *indicatorColor;

borderColor

Define color for captcha button border. Defaults to 0xcccccc. Animatable.

Declaration

@property (nonatomic, strong) UIColor *borderColor;

borderWidth

Define width for captcha button border. Defaults to 1.0. Animatable.

Declaration

@property (nonatomic, assign) CGFloat *borderWidth;

cornerRadius

Define captcha button corner radius. Defaults to 3.0. Animatable.

Declaration

@property (nonatomic, assign) CGFloat *cornerRadius;

Method

initWithFrame:captchaManager:

Initializes and returns a newly allocated captcha button object with the specified frame rectangle.

Declaration

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

Parameters

Param Description
frame The frame rectangle for the button, measured in points.
captchaManager Instance of captcha manager

Return Value

A initialized captcha button object.

startCaptcha

Start the verfication

Declaration

- (void)startCaptcha;

Discussion

Depending on captcha state, call GT3CaptchaManager instance method startGTCaptchaWithAnimated:, requestGTCaptcha, showGTViewIfRegiested inner.

stopCaptcha

Stop the verification

Declaration

- (void)stopCaptcha;

Discussion

Call GT3CaptchaManager instance method stopGTCaptcha inner.

resetCaptcha

Reset the captcha/verification

Declaration

- (void)resetCaptcha;

Discussion

Call GT3CaptchaManager instance method resetCaptcha inner.

updateTitleLabel:

Update captcha button tips label instantly.

Declaration

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

Parameters

Param Description
title An attributed string for title

GT3CaptchaManager

Property

delegate

Delegate of captcha manager

Declaration

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

viewDelegate

View delegate of captcha

Declaration

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

statisticDelegate

Statistic delegate

Declaration

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

captchaState

Captcha status

Declaration

@property (nonatomic, readonly) GT3CaptchaState captchaState;

isShowing

Whether captcha challenge is showing

Declaration

@property (nonatomic, readonly) BOOL isShowing;

API_1

The API to get the parameters for starting captcha, e.g. challenge, gt, success.

Declaration

@property (nonatomic, readonly) NSURL *API_1;

API_2

The API to process the secondary verification

Declaration

@property (nonatomic, readonly) NSURL *API_2;

gt_captcha_id

The captcha ID (i.e. gt) of the manager, if the manager started success.

Declaration

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

gt_challenge

The challenge (i.e. challenge) of the manager, if the manager started success.

Declaration

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

gt_success_code

The current server status (i.e. success) of the captcha

Declaration

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

Discussion

The value of the property is @"0" for uptime, or @"1" for downtime.

maskColor

Color of the mask when showing the captcha challenge

Declaration

@property (nonatomic, strong) UIColor *maskColor;

Method

sdkVersion

Version of SDK

Declaration

+ (NSString *)sdkVersion;

sharedGTManager

The shared instance of captcha manager

Declaration

+ (instancetype)sharedGTManager;

initWithAPI1:API2:timeout:

The designated initializer, i.e. captcha initialization method

Declaration

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

Parameters

Param Description
api_1 The API to get verification parameters
api_2 The API for the secondary verification
timeout The timeout of the request

Return Value

Returns a newly initialized GT3CaptchaManager instance

Discussion

Declare with NS_DESIGNATED_INITIALIZER

cancelRequest

Cancel asynchronous request

Declaration

- (void)cancelRequest;

Discussion

Call this method to cancel all of the executed NSURLSessionDataTask

configureGTest:challenge:success:withAPI2:

Custom configure verification by gt, chanllenge and success

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 captcha ID
gt_challenge challenge
gt_success_code success
api_2 The API for the secondary verification

Discussion

A challenge could be used for only once

registerCaptcha:

Register a session for captcha

Declaration

- (void)registerCaptcha:(GT3CaptchaDefaultBlock)completionHandler;

Parameters

Param Description
completionHandler The block of handler register callback

Discussion

Should be called before startGTCaptchaWithAnimated:

See also

GT3CaptchaDefaultBlock

registerCaptchaWithCustomAsyncTask:completion:

Register the verification process with api1 and api2 tasks

Declaration

- (void)registerCaptchaWithCustomAsyncTask:(id<GT3AsyncTaskProtocol>)customAsyncTask completion:(GT3CaptchaDefaultBlock)completionHandler;

Parameters

Param Description
customAsyncTask Custom async task object
completionHandler Callback upon registration’s completion

Discussion

Should be invoked before startGTCaptchaWithAnimated:

Seealso

GT3CaptchaDefaultBlock and GT3AsyncTaskProtocol

startGTCaptchaWithAnimated:

Start the verification

Declaration

- (void)startGTCaptchaWithAnimated:(BOOL)animated;

Parameters

Param Description
animated If YES, the captcha is being started and using animation.

stopGTCaptcha

Stop the verification

Declaration

- (void)stopGTCaptcha;

resetGTCaptcha

Reset the verification

Declaration

- (void)resetGTCaptcha;

closeGTViewIfIsOpen

Close GTView if open

Declaration

- (void)closeGTViewIfIsOpen;

getCookieValue:

Get cookie value

Declaration

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

Parameters

Param Description
cookieName Key of cookie

Return Value

Return the value of cookie

useGTViewWithTimeout:

Set timeout for GTView loading the resources

Declaration

- (void)useGTViewWithTimeout:(NSTimeInterval)timeout;

Parameters

Param Description
timeout Timeout duration

useGTViewWithCornerRadius:

Configure the corner radius for the GT3View

Declaration

- (void)useGTViewWithCornerRadius:(CGFloat)cornerRadius;

Parameters

Param Description
cornerRadius Corner radius

Discussion

Default is 2px. The maximum value is 30px.

useGTViewWithParams:

Configure the parameters of loading CAPTCHA resource

Declaration

- (void)useGTViewWithParams:(NSDictionary *)params;

Parameters

Param Description
params Custom parameters

Discussion

The parameters will be converted to form format for loading web resources.

useGTViewWithTimeout:

Set request timeout of GTView

Declaration

- (void)useGTViewWithTimeout:(NSTimeInterval)timeout;

Parameters

Param Description
timeout The timeout of the request

useAnimatedAcitvityIndicator:withIndicatorType:

Custom activity indicator.

Declaration

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

Parameters

Param Description
animationBlock The block of handling activity indicator animation
type Type of the activity indicator

useVisualViewWithEffect:

Set the blur effect for background

Declaration

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

Parameters

Param Description
blurEffect Blur effect

Discussion
Only support iOS 8+

useLanguage:

Switch language

Declaration

- (void)useLanguage:(GT3LanguageType)type;

Discussion
The default language is the same with system language.

Seealso

The language could be changed. Please find the details in GT3LanguageType.

useLanguageCode:

Configure the language with lang code

Declaration

- (void)useLanguageCode:(NSString *)lang;

Parameters

Param Description
lang Language code. Refer below for the list

Discussion

The default is system language. Use English if the system language is not supported.

Language Key
Arabic ar
German de
English en
Spanish (Europe) es
French fr
Indonesian id
Japanese ja
Korean ko
Portuguese (Europe) pt-PT
Russian ru
Chinese (Simplified) zh-CN
Chinese (Hong Kong) zh-HK
Chinese (Taiwan) zh-TW

useServiceNode:

Switch the server node

Declaration

- (void)useServiceNode:(GT3CaptchaServiceNode)node;

Parameters

Param Description
node Server node

Discussion

The default is CN node. Configure this before using the corresponding server node. Otherwise, the access to the server will be disabled.

Seealso

See also GT3CaptchaServiceNode

disableSecurityAuthentication:

Disable HTTPS.

Declaration

- (void)disableSecurityAuthentication:(BOOL)disable;

Parameters

Param Description
disable NO if using the HTTPS, or YES if disable the HTTPS.

Discussion
The default option is to enable the https.

disableBackgroundUserInteraction:

Disable user interacts with background

Declaration

- (void)disableBackgroundUserInteraction:(BOOL)disable;

Parameters

Param Description
disable NO if user cannot interact with background, or YES if they can.

Discussion

The default option is to enable the background interaction .

enableNetworkReachability:

Enable the networt reachability test.

Declaration

- (void)enableNetworkReachability:(BOOL)enable;

Parameters

Param Description
enable YES if networt reachability test is enabled, or NO if disabled.

Discussion
The default option is to enable the network reachability test.

enableDebugMode:

Debug Mode

Declaration

- (void)enableDebugMode:(BOOL)enable;

Parameters

Param Description
enable YES if the debug mode is enabled, or NO if disabled.

Discussion
The debug mode is disabled by default.

GT3RegisterParameter

Property

gt

CAPTCHA ID(gt)

Declaration

@property (nonatomic, strong) NSString *gt;

challenge

CAPTCHA challenge id

Declaration

@property (nonatomic, strong) NSString *challenge;

success

Service status。@(1) is available, @(0) is downtime。

Declaration

@property (nonatomic, strong) NSNumber *success;

GT3ValidationParam

Property

code

Initial verification result。@”1” success, @”0” fail。

Declaration

@property (nonatomic, strong) NSString *code;

result

Verification result. Use the result in validate api to request the final result

Declaration

@property (nullable, nonatomic, strong) NSDictionary *result;

message

Additional message

Declaration

@property (nullable, nonatomic, strong) NSString *message;

GT3Error

GT3Error object

GT3ErrorType

Error type

Declaration

typedef NS_ENUM(NSUInteger, GT3ErrorType) {
/** The verifcation process is interrupted */
GT3ErrorTypeUser,
/** Server error */
GT3ErrorTypeServer,
/** Internal network error */
GT3ErrorTypeNetWorking,
/** WebView throws error */
GT3ErrorTypeWebView,
/** Javascript throws error */
GT3ErrorTypeJavaScript,
/** Internal decoding error */
GT3ErrorTypeDecode,
/** Unknow error */
GT3ErrorTypeUnknown
};

Property

metaData

The metadata receives when error occurs. If no metadata, return nil.

Declaration

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

gtDescription

Extra error description provided by GeeTest.

Declaration

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

originalError

Original Error

Declaration

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

Method

errorWithDomainType:code:userInfo:withGTDesciption:

Initialize GT3Error with provided detailed parameters

Declaration

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

Parameters

Param Description
type Error type defined by GeeTest
code Error code
dict userInfo of error
description Description of error

errorWithDomainType:originalError:withGTDesciption:

Encapsulate to GT3Error with the provided NSError

Declaration

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

Parameters

Param Description
type Error type defined by GeeTest
error Original object of NSError
description Description of error

GT3Utils

GT3CaptchaState

Captcha state

Declaration

typedef NS_ENUM(NSInteger, GT3CaptchaState) {
/**CAPTCHA inactive */
GT3CaptchaStateInactive,
/** CAPTCHA active */
GT3CaptchaStateActive,
/** CAPTCHA initial */
GT3CaptchaStateInitial,
/** Collecting gyroscope data */
GT3CaptchaStateCollecting,
/** Waiting to submit*/
GT3CaptchaStateWaiting,
/** Waiting for response*/
GT3CaptchaStateComputing,
/** Verification success*/
GT3CaptchaStateSuccess,
/** Verification fail*/
GT3CaptchaStateFail,
/** Error occurs*/
GT3CaptchaStateError
};

GT3CaptchaServiceNode

Configure the server node

Declaration

typedef NS_ENUM(NSInteger, GT3CaptchaServiceNode) {
/** CN server node*/
GT3CaptchaServiceNodeCN = 0,
/** NA server node*/
GT3CaptchaServiceNodeNA,
/** Default server node*/
GT3CaptchaServiceNodeDefault = GT3CaptchaServiceNodeCN
};

GT3CaptchaMode

Captcha mode

Declaration

typedef NS_ENUM(NSInteger, GT3CaptchaMode) {
/** Default(i.e.normal) Mode*/
GT3CaptchaModeDefault,
/** Failback Mode*/
GT3CaptchaModeFailback
};

GT3SecondaryCaptchaPolicy

The policy of secondary verification to update captcha button

Declaration

typedef NS_ENUM(NSInteger, GT3SecondaryCaptchaPolicy) {
/** Pass the secondary verification */
GT3SecondaryCaptchaPolicyAllow,
/**Fail the secondary verification */
GT3SecondaryCaptchaPolicyForbidden
};

GT3LanguageType

Language options

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,
/** Indonesian*/
GT3LANGTYPE_ID,
/** Arabic */
GT3LANGTYPE_AR,
/** German*/
GT3LANGTYPE_DE,
/** Spanish */
GT3LANGTYPE_ES,
/** French */
GT3LANGTYPE_FR,
/** Portuguese */
GT3LANGTYPE_PT_PT,
/** Russian */
GT3LANGTYPE_RU,
/** System language */
GT3LANGTYPE_AUTO = 999
};

GT3ActivityIndicatorType

Activity indicator type

Declaration

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

GT3CaptchaDefaultBlock

Block of verification callback

Declaration

typedef void(^GT3CaptchaDefaultBlock)(void);

GT3IndicatorAnimationViewBlock

Block of activity indicator of animation

Declaration

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

Parameters

Param Description
layer Layer of activity indicator
size Size of layer. Default value is {64, 64}.
color Color of layer. Default value is blue. [UIColor colorWithRed:0.3 green:0.6 blue:0.9 alpha:1]