iOS Integration Guide

The EngageLab Behavioral Verification iOS SDK is designed for developers integrating with iOS native client development. The SDK does not rely on any third-party libraries.

Product Overview

Environment Requirements

Importing the SDK

1. If you are adding the SDK manually, drag the GTCaptcha4.framework file obtained from the download into your project, ensuring that Copy items if needed is checked.

   Use the Linked Frameworks and Libraries method to import the framework. After dragging GTCaptcha4.framework into the project, ensure that the .framework file is added to PROJECT -> Build Phases -> Linked Frameworks and Libraries.

   

   The SDK provides an XCFramework format, located in the SDK -> XCFramework directory under the downloaded files as GTCaptcha4.xcframework.

2. For Category in static libraries, add -ObjC to Other Linker Flags under Build Settings for the corresponding target.

   

3. You also need to include GT4Captcha4.Bundle in your project; otherwise, verification will not work. Drag the GTCaptcha4.Bundle from the SDK directory into your project.

   

At WWDC23, Apple announced new privacy policies for applications (including SDKs), with a dedicated session Get started with privacy manifests - WWDC23 - Videos - Apple Developer. On July 27, Apple released a news update stating that starting in Fall 2023, if newly uploaded applications use related APIs without providing a privacy manifest, you will receive an email notification. Starting in Spring 2024, privacy manifests will become mandatory. For the APIs involved and usage reasons, refer to: Describing use of required reason API | Apple Developer Documentation. If the usage reason is not listed, you can directly submit a specific usage explanation.

To create a new privacy manifest, refer to Privacy manifest files | Apple Developer Documentation.

The Behavioral Verification iOS SDK uses some functions to obtain disk capacity and environment detection information for risk control purposes, involving the categories NSPrivacyAccessedAPICategoryDiskSpace and NSPrivacyAccessedAPICategoryFileTimestamp. This is hereby stated.

Configuration Interface

Refer to the Product Structure Process of Behavioral Verification. You must first set up the corresponding server-side interface on your backend and configure the captchaId and Key obtained from the EngageLab Management Console.

Developers integrating the SDK need to use the following interfaces provided by the iOS SDK:

1. Configure verification initialization using the ID.
2. Start verification.
3. Obtain verification result parameters and perform secondary validation on the submitted result parameters to prevent forgery.
4. Handle potential issues during verification using error delegate methods.

You need to adhere to the <GTCaptcha4SessionTaskDelegate> protocol to handle verification results and possible errors.

Refer to the Code Examples below for integration code.

Compile and Run Your Project

Compile your project and experience behavioral verification.

Code Examples

Initialization and Verification Call

Import the header file of the verification dynamic library GTCaptcha4.framework in your project.

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

Take integration within a UIButton as an example.

1. Initialization

   Initialize an instance of the verification manager GTCaptcha4Session. In the UIButton initialization method, call the registration method of the GTCaptcha4Session instance to obtain registration data:

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// Create instance GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// Set intermediate page address, must be set as per the example config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// Set apiServer and staticServer, must be set as per the example config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// Request protocol config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // Pre-initialize the verification session. If not called here, lazy loading will be used. [self captchaSession]; [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside]; }

                 
                 #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   @interface ViewController () <GTCaptcha4SessionTaskDelegate>
   
   @property (strong, nonatomic) IBOutlet UIButton *startBtn;
   
   @property (nonatomic, strong) GTCaptcha4Session *captchaSession;
   
   @end
   
   @implementation ViewController
   
   - (GTCaptcha4Session *)captchaSession {
       if (!_captchaSession) {
           /// Create instance
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// Set intermediate page address, must be set as per the example
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// Set apiServer and staticServer, must be set as per the example
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// Request protocol
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // Pre-initialize the verification session. If not called here, lazy loading will be used.
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   This code block in the floating window

   For other optional configuration items, see the interfaces or properties defined in GTCaptcha4SessionConfiguration.

2. Call Verification

   After initialization, call the following method to perform verification:

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

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

   This code block in the floating window

Handling Verification Results

Verification is only complete after validating the verification results. You need to handle the following delegate methods after adhering to the GTCaptcha4SessionTaskDelegate protocol:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // code is @"1" if the user completed the verification, @"0" if the user failed verification
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Convert dictionary to form format for submission (construct based on actual interface data format requirements)
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id  _Nonnull key, id  _Nonnull obj, BOOL * _Nonnull 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];

            // Backend verification interface provided by the business, must be set as per the example
            NSURL *url = [NSURL URLWithString:@"https://captcha-api.engagelab.com/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // Submit to the backend for result validation
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // Handle verification results
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

Handling Verification Errors

Unexpected errors may occur during verification. You can handle them in the following delegate method after adhering to the GTCaptcha4SessionTaskDelegate protocol:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // Display error information and error code to the user

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

            

It is strongly recommended to display both the error reason and error code to the user when showing verification errors, to facilitate troubleshooting of online issues.

Swift Example

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