GeeTest captcha iOS SDK supports for native iOS. The SDK doesn’t contain any third-party library.

Development environment

Item Description
Target iOS 7+
Development environment Xcode 9.0
Dependency Webkit.framework, JavascriptCore.framework
Third-party dependency None


Item Description
Data communication flow chart Data communication flow chart, Interaction flow chart
SDK API reference gt3-ios-docs or check the header files
Error code Error Code


Download SDK & Demo

Please click the link below to download the latest SDK (in .zip format).

Add SDK via CocoaPods

Please add the following to the file named Podfile in your workspace

pod 'GT3Captcha-iOS'

Import SDK

  1. If you add the SDK manually, please drag and drop the GT3Captcha.framework into the project and select Copy items if needed.


    Please use Linked Frameworks and Libraries to import the framework。After you have added GT3Captcha.framework into the project, please check if .framework has been successfully added in PROJECT -> Build Phases -> Linked Frameworks and Libraries.


  2. For the Category in static libraries, please add -ObjC flag via Build Settings->Other Linker Flags for the corresponding target. Please add -ObjC flag. If it doesn’t work, please add -all_load.


  3. SDK version 0.9.0 and later needs to add GT3Captcha.Bundle to project. Drag and drop GT3Captcha.Bundle from the .zip to the project.


Please firstly integrate server SDK, configure the id and key (get from GeeTest dashboard) and implement API1 and API2 in the initial method.

To use the SDK, please firstly finish the following steps.

  1. Initialize captcha
  2. Start captcha
  3. Get the verification result
  4. Handle errors

There are two styles of captcha button integration. Please choose one of them.

  1. Use GT3CaptchaManager and bind with users events (Bind GeeTest captcha to your custom button, i.e. invisible captcha)
  2. Use GT3CaptchaButton (Integrate with GeeTest captcha button)

Whatever integration method is used, the project must conform to <GTCaptchaManagerDelegate> protocol to process verification results and the possible returned errors.

Please refer to the following examples for integration code.

Compile and run your project

Compile your project and experience GeeTest captcha.

Visual presentation

  1. Bind GeeTest captcha to a custom button


  2. Integrate with GeeTest captcha button


Code examples

Initialize captcha and start captcha

Import static library GT3Captcha.framework in header files

#import <GT3Captcha/GT3Captcha.h>

Bind GeeTest captcha to a custom button

The following example bind the captcha with UIButton

  1. Initialize captcha
    Instance of captcha initialization manager GTCaptchaManager. Call the register method in GTCaptchaManager instance to get register data.

    - (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. Start captcha

    After finished with captcha initialization and register, call the following method to activate captcha.

    [self.manager startGTCaptchaWithAnimated:YES];

Integrate with GeeTest captcha button (use GT3CaptchaButton in SDK)

The example integrate captcha with ViewController

  1. Initialize captcha
    Initial the instance of GTCaptchaManager and assign this instance to GTCaptchaButton.Then, add the GTCaptchaButton to [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. Start captcha

    Click the captcha button or use the following method to activate captcha.

    [captchaButton startCaptcha];

Get the verification result

Only after finishing the secondary verification, the verification process is complete. Please conform to GTCaptchaManagerDelegate protocol and process the following delegate methods.

- (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]);
else {
NSLog(@"validate error: %ld, %@", (long)error.code, error.localizedDescription);

Handle errors

During the verification process, there might be some errors. Please conform to GTCaptchaManagerDelegate protocol and handle the errors with the following delegate methods.

- (void)gtCaptcha:(GTCaptchaManager *)manager errorHandler:(GTError *)error {
NSLog(@"error: %@", error.localizedDescription);

Please check the link for the error codes. GT3Error

Optional captcha Delegate Methods

Modify API1 request

Since some companies might require authentication or custom parameters, you could use the following delegate methods to custom the API1 request.

- (void)gtCaptcha:(GT3CaptchaManager *)manager willSendRequestAPI1:(NSURLRequest *)originalRequest withReplacedHandler:(void (^)(NSURLRequest *))replacedHandler {
NSMutableURLRequest *mRequest = [originalRequest mutableCopy];

TO-DO, 处理mRequest, 进行自定义


Please check AsyncButton file in the following link for custom API1 & API2 request example. Code Example

Modify API2 request

Since some companies might require authentication or custom parameters, you could use the following delegate methods to custom the API2 request.

- (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;

Please check AsyncButton file in the following link for custom API1 & API2 request example. Code Example

Get verification parameters

To get the verification parameters, you can use the following delegate methods.

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

Disable the default API1 request

Please refer to the following example to disable the default API1 request.

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

Since the API1 request has been disabled, please configure captcha parameters manually, otherwise you cannot start captcha.

// 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];

Disable the default API2 request

Please refer to the following example to disable the default API2 request.

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

Discussion: After the API2 request has been disabled, the verification result prompt in the captcha button depends on the code in gtCaptcha:didReceiveCaptchaCode:result:message:. The @"1" refers to verification success.

Other APIs

Please check the API reference for further details.

Please refer to the Demo project for detailed examples.