iOS Integration

Requirements

Item	Requirement
Deployment Target	iOS 9.0+
Development Environment	Xcode 13.0+
System Dependencies	`Webkit.framework`
Third-party Dependencies	None

The SDK is provided in XCFramework format, supporting both devices and simulators.

Installation

Import XCFramework

Drag the downloaded GeeLabCaptcha.xcframework file into your project, ensuring that Copy items if needed is checked.

Import the framework using the Linked Frameworks and Libraries method. After dragging it in, verify that the .framework file has been added to PROJECT -> Build Phases -> Linked Frameworks and Libraries.

Configure Linker Flags

For Category in static libraries, add -ObjC to the corresponding target's Build Settings -> Other Linker Flags.

Import Resource Bundle

Drag the GeeLabCaptcha.Bundle from the SDK path into your project.

Important: You must import GeeLabCaptcha.Bundle, otherwise the captcha will not work properly.

Privacy Manifest

Starting in Spring 2024, Apple requires all apps and SDKs to provide a privacy manifest.

The Behavioral Verification iOS SDK uses the following API categories for risk control purposes:

NSPrivacyAccessedAPICategoryDiskSpace - Retrieve disk capacity information
NSPrivacyAccessedAPICategoryFileTimestamp - Environment detection information

Reference Documentation:

Basic Integration

Import Header File

ViewController.m

#import <GeeLabCaptcha/GeeLabCaptcha.h>

Initialize Captcha Session

ViewController.m

#define captchaID @"YOUR_CAPTCHA_ID"

@interface ViewController () <GeeLabCaptchaSessionTaskDelegate>

@property (strong, nonatomic) IBOutlet UIButton *startBtn;
@property (nonatomic, strong) GeeLabCaptchaSession *captchaSession;

@end

@implementation ViewController

- (GeeLabCaptchaSession *)captchaSession {
    if (!_captchaSession) {
        _captchaSession = [GeeLabCaptchaSession sessionWithCaptchaID:captchaID];
        _captchaSession.delegate = self;
    }
    return _captchaSession;
}

- (void)viewDidLoad {
    [super viewDidLoad];

    // Initialize captcha session in advance (recommended)
    [self captchaSession];

    [self.startBtn addTarget:self
                      action:@selector(start)
            forControlEvents:UIControlEventTouchUpInside];
}

- (void)start {
    [self.captchaSession verify];
}

@end

Initializing the captcha session in advance can improve user experience and reduce waiting time.

Import Framework

ViewController.swift

import GeeLabCaptcha

Initialize Captcha Session

ViewController.swift

class ViewController: UIViewController {
    private let captchaID = "YOUR_CAPTCHA_ID"
    private var captchaSession: GeeLabCaptchaSession?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Initialize captcha session
        captchaSession = GeeLabCaptchaSession(captchaID: captchaID)
        captchaSession?.delegate = self
    }

    @IBAction func startVerification(_ sender: UIButton) {
        captchaSession?.verify()
    }
}

extension ViewController: GeeLabCaptchaSessionTaskDelegate {
    // Implement delegate methods
}

For more Swift example code, please refer to the DefaultDemoViewController.swift file in the official Demo.

Configuration Options

Custom Configuration

Customize verification behavior through GeeLabCaptchaSessionConfiguration:

Custom Configuration Example

GeeLabCaptchaSessionConfiguration *config = [GeeLabCaptchaSessionConfiguration defaultConfiguration];

// Set timeout (seconds)
config.timeout = 8.0f;

// Set language
config.language = @"zh-cn";

// Set additional parameters
config.additionalParameter = @{
    @"hideSuccess": @(1),  // Hide success message
    @"loading": @""        // Custom loading
};

// Create session with custom configuration
_captchaSession = [GeeLabCaptchaSession sessionWithCaptchaID:captchaID
                                              configuration:config];

Configuration Parameters

Parameter	Type	Description
`timeout`	`NSTimeInterval`	Timeout duration (seconds)
`language`	`NSString`	Language code (e.g., `zh-cn`, `en`)
`additionalParameter`	`NSDictionary`	Additional parameters
`resourcePath`	`NSString`	Custom resource path

Handling Verification Results

Implement the GeeLabCaptchaSessionTaskDelegate protocol to handle verification results:

Handle Verification Success

- (void)geelabCaptchaSession:(GeeLabCaptchaSession *)captchaSession
                  didReceive:(NSString *)code
                      result:(NSDictionary *)result {
    NSLog(@"result: %@", result);

    // code equals @"1" indicates user completed verification
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Construct form data
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id key, id obj, BOOL *stop) {
                if ([key isKindOfClass:[NSString class]] &&
                    [obj isKindOfClass:[NSString class]]) {
                    NSString *kvPair = [NSString stringWithFormat:@"%@=%@", key, obj];
                    [kvPairs addObject:kvPair];
                }
            }];

            NSString *formStr = [kvPairs componentsJoinedByString:@"&"];
            NSData *data = [formStr dataUsingEncoding:NSUTF8StringEncoding];

            // Submit to backend for verification
            NSURL *url = [NSURL URLWithString:@"https://your-api.com/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod = @"POST";
            request.HTTPBody = data;

            [[[NSURLSession sharedSession] dataTaskWithRequest:request
                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                if (!error && data) {
                    NSString *msg = [[NSString alloc] initWithData:data
                                                          encoding:NSUTF8StringEncoding];
                    NSLog(@"Verification result: %@", msg);
                } else {
                    NSLog(@"Verification error: %@", error);
                }
            }] resume];
        }
    }
}

Important: You must perform secondary verification on the server side. Do not rely solely on client-side results.

Handle Verification Error

- (void)geelabCaptchaSession:(GeeLabCaptchaSession *)captchaSession
              didReceiveError:(GeeLabCaptchaError *)error {
    // Display error message and error code to user
    NSString *message = [NSString stringWithFormat:@"Verification error [%@]: %@",
                        error.code, error.description];

    UIAlertController *alert = [UIAlertController
        alertControllerWithTitle:@"Verification Failed"
        message:message
        preferredStyle:UIAlertControllerStyleAlert];

    [alert addAction:[UIAlertAction actionWithTitle:@"OK"
                                              style:UIAlertActionStyleDefault
                                            handler:nil]];

    [self presentViewController:alert animated:YES completion:nil];

    // Log error details
    NSLog(@"Verification error details: %@", error.description);
}

Strongly recommended to display the error code along with the error message to users, which helps troubleshoot production issues.

Common Issues

Next Steps

Check Server Integration to learn about backend verification
Read API Reference for complete API documentation
View FAQ to resolve integration issues

iOS Integration

Language setting not taking effect?

How to remove or customize loading?

Error linking ARC library when running project with Xcode 14.3?

On this page