logo文档
CAPTCHA
文档首页
客户端SDK服务端数据安全
搜索
简体中文
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
登录
客户端SDK / IOS / API 指南

iOS SDK API

最新更新：2025-11-07

GTCaptcha4SessionTaskDelegate

验证会话任务代理协议

gtCaptchaSession:didReceive:result:

回调验证会话的结果参数。

Declaration

- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)status result:(nullable NSDictionary *)result;
              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession
              didReceive:(NSString *)status
                  result:(nullable NSDictionary *)result;
此代码块在浮窗中显示

Parameters

Param Description
captchaSession 验证会话
status 状态码。@"0"/@"1": 未完成/完成。
当 status 为 @"1" 时，则为成功，需要对结果进行二次校验。
result 结果校验参数。

Discussion

拿到验证结果的参数后，需要提交到业务服务端，完成参数的校验。result 示例：

{ pass_token = "eb6d2e064524ae96ddc99a0e6e15f95dbb234008d108f0db269f27d426bcf3c6"; gen_time = "1660894030"; captcha_output = "fI9I34MDjVi10gJO_EqXwNpN8hK0rYLEPVWSDE4W6kc1umDoTHIlD_t6YQNNpPG2tJlKR8he6WFWkkllU8goGeNVNOzhqmAm256BpK8qAEHNrOjHzkNagfIcx_A21ssPrG6YlnnHFx3PfBnbrn5fb2aKDIi0I5xmCUjxq0dsFuANLIQVtllMjkJ7-1l_j-Wz"; captcha_id = "647f5ed2ed8acb4be36784e01556bb71"; lot_number = "0861c607d519469b9117d0c6dd551fe3"; }
              
              {
    pass_token = "eb6d2e064524ae96ddc99a0e6e15f95dbb234008d108f0db269f27d426bcf3c6";
    gen_time = "1660894030";
    captcha_output = "fI9I34MDjVi10gJO_EqXwNpN8hK0rYLEPVWSDE4W6kc1umDoTHIlD_t6YQNNpPG2tJlKR8he6WFWkkllU8goGeNVNOzhqmAm256BpK8qAEHNrOjHzkNagfIcx_A21ssPrG6YlnnHFx3PfBnbrn5fb2aKDIi0I5xmCUjxq0dsFuANLIQVtllMjkJ7-1l_j-Wz";
    captcha_id = "647f5ed2ed8acb4be36784e01556bb71";
    lot_number = "0861c607d519469b9117d0c6dd551fe3";
}
此代码块在浮窗中显示

gtCaptchaSession:didReceiveError:

回调验证会话中发生的错误。

Declaration

- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error;
              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession
         didReceiveError:(GTC4Error *)error;
此代码块在浮窗中显示

Parameters

Param Description
captchaSession 验证会话
error 错误描述对象

Seealso

Error

GTCaptcha4Session

验证会话

delegate

验证会话任务代理。

Declaration

@property (nonatomic, weak) id<GTCaptcha4SessionTaskDelegate> delegate;
              
              @property (nonatomic, weak) id<GTCaptcha4SessionTaskDelegate> delegate;
此代码块在浮窗中显示

captchaID

当前验证会话的验证 ID。

Declaration

@property (nonnull, readonly, nonatomic, strong) NSString *captchaID;
              
              @property (nonnull, readonly, nonatomic, strong) NSString *captchaID;
此代码块在浮窗中显示

challenge

当前验证会话的流水号。

Declaration

@property (nullable, readonly, nonatomic, strong) NSString *challenge;
              
              @property (nullable, readonly, nonatomic, strong) NSString *challenge;
此代码块在浮窗中显示

configuration

当前验证会话的配置。

Declaration

@property (nonnull, readonly, nonatomic, strong) GTCaptcha4SessionConfiguration *configuration;
              
              @property (nonnull, readonly, nonatomic, strong) GTCaptcha4SessionConfiguration *configuration;
此代码块在浮窗中显示

sessionWithCaptchaID:

创建一个新的验证会话实例。

Declaration

+ (instancetype)sessionWithCaptchaID:(NSString *)captchaID;
              
              + (instancetype)sessionWithCaptchaID:(NSString *)captchaID;
此代码块在浮窗中显示

Parameters

Param Description
captchaID 验证ID

Return Value

一个新的 GTCaptcha4Session 实例

sessionWithCaptchaID:configuration:

创建一个新的验证会话实例。

Declaration

+ (instancetype)sessionWithCaptchaID:(NSString *)captchaID configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
              
              + (instancetype)sessionWithCaptchaID:(NSString *)captchaID
                       configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
此代码块在浮窗中显示
Param Description
captchaID 验证ID
configuration 会话配置

Return Value

一个新的 GTCaptcha4Session 实例

initWithCaptchaID:

创建一个新的验证会话实例。

Declaration

- (instancetype)initWithCaptchaID:(NSString *)captchaID;
              
              - (instancetype)initWithCaptchaID:(NSString *)captchaID;
此代码块在浮窗中显示

Parameters

Param Description
captchaID 验证ID

Return Value

一个新的 GTCaptcha4Session 实例

initWithCaptchaID:configuration:

创建一个新的验证会话实例。

Declaration

- (instancetype)initWithCaptchaID:(NSString *)captchaID configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
              
              - (instancetype)initWithCaptchaID:(NSString *)captchaID
                    configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
此代码块在浮窗中显示
Param Description
captchaID 验证ID
configuration 会话配置

Return Value

一个新的 GTCaptcha4Session 实例

verify

开始验证。

Declaration

- (void)verify;
              
              - (void)verify;
此代码块在浮窗中显示

cancel

取消验证。

Declaration

- (void)cancel;
              
              - (void)cancel;
此代码块在浮窗中显示

sdkVersion

获取 SDK 版本号。

Declaration

+ (NSString *)sdkVersion;
              
              + (NSString *)sdkVersion;
此代码块在浮窗中显示

GTCaptcha4SessionConfiguration

验证会话配置

GTC4UserInterfaceStyle

验证界面样式。

Declaration

typedef NS_ENUM(NSInteger, GTC4UserInterfaceStyle) { /** 跟随系统样式 */ GTC4UserInterfaceStyleSystem = 0, /** 普通样式 */ GTC4UserInterfaceStyleLight, /** 暗黑样式 */ GTC4UserInterfaceStyleDark, /** 默认样式 */ GTC4UserInterfaceStyleDefault = GTC4UserInterfaceStyleLight };
              
              typedef NS_ENUM(NSInteger, GTC4UserInterfaceStyle) {
    /** 跟随系统样式 */
    GTC4UserInterfaceStyleSystem = 0,
    /** 普通样式 */
    GTC4UserInterfaceStyleLight,
    /** 暗黑样式 */
    GTC4UserInterfaceStyleDark,
    /** 默认样式 */
    GTC4UserInterfaceStyleDefault = GTC4UserInterfaceStyleLight
};
此代码块在浮窗中显示

resourcePath

远程访问静态资源的完整路径, 默认为空。

Declaration

@property (nullable, nonatomic, strong) NSString *resourcePath;
              
              @property (nullable, nonatomic, strong) NSString *resourcePath;
此代码块在浮窗中显示

protocol

远程访问静态资源时的协议，默认 @“https”。

Declaration

@property (nonatomic, strong) NSString *protocol;
              
              @property (nonatomic, strong) NSString *protocol;
此代码块在浮窗中显示

userInterfaceStyle

界面和状态栏样式，默认普通白色。

Declaration

@property (nonatomic, assign) GTC4UserInterfaceStyle userInterfaceStyle;
              
              @property (nonatomic, assign) GTC4UserInterfaceStyle userInterfaceStyle;
此代码块在浮窗中显示

backgroundColor

背景颜色，默认透明。

Declaration

@property (nonatomic, strong) UIColor *backgroundColor;
              
              @property (nonatomic, strong) UIColor *backgroundColor;
此代码块在浮窗中显示

debugEnable

调试模式开关，默认关闭。

Declaration

@property (nonatomic, assign) BOOL debugEnable;
              
              @property (nonatomic, assign) BOOL debugEnable;
此代码块在浮窗中显示

backgroundUserInteractionEnable

点击背景的交互，默认开启。

Declaration

@property (nonatomic, assign) BOOL backgroundUserInteractionEnable;
              
              @property (nonatomic, assign) BOOL backgroundUserInteractionEnable;
此代码块在浮窗中显示

timeout

请求超时时长，默认 8 秒。

Declaration

@property (nonatomic, assign) NSTimeInterval timeout;
              
              @property (nonatomic, assign) NSTimeInterval timeout;
此代码块在浮窗中显示

language

语言，默认跟随系统。指定语言请参考语言短码。

Declaration

@property (nonatomic, strong) NSString *language;
              
              @property (nonatomic, strong) NSString *language;
此代码块在浮窗中显示

supportedInterfaceOrientations

支持的横竖屏方向。

Declaration

@property (assign, nonatomic) UIInterfaceOrientationMask supportedInterfaceOrientations;
              
              @property (assign, nonatomic) UIInterfaceOrientationMask supportedInterfaceOrientations;
此代码块在浮窗中显示

additionalParameter

额外的参数, 默认为空。参数将被组装后提交到engagelab。

Declaration

@property (nullable, nonatomic, strong) NSDictionary *additionalParameter;
              
              @property (nullable, nonatomic, strong) NSDictionary *additionalParameter;
此代码块在浮窗中显示

Discussion

支持的键值列表如下：

|Key |Type |Description|Default Value| |---- |---- |---------- | ----------- | | @"loading" | NSString | 自定义加载中的状态指示器，WebView 加载 html 的 loading 资源相对路径。设置空字符串表示取消 loading。 | @"./gt4-loading.gif" | | @"rem" | NSNumber | 设置验证码整体的缩放比例 | @(1) | | @"hideBar" | NSArray<NSString *> * | 隐藏后续验证界面的关闭按钮、刷新按钮。设置 @[@"close", @"refresh"] 则为隐藏关闭和刷新按钮。 | @[] | | @"nextWidth" | NSString | 验证码弹窗的宽度，需要携带单位，如 @"300px" | nil | | @"riskType" | NSString | 结合风控融合，指定验证形式 | nil | | @"hideSuccess" | NSNumber | 隐藏验证成功弹窗，@(0)/@(1) 为不隐藏或隐藏 | @(0) |

Sample Code

#define captchaID @"1234567890abcdef" GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; NSMutableDictionary *params = [@{} mutableCopy]; [params setValue:@(1.25) forKey:@"rem"]; // 放大 1.25 倍 [params setValue:@[@"close", @"refresh"] forKey:@"hideBar"]; // 隐藏关闭按钮及刷新按钮 [params setValue:@"300px" forKey:@"nextWidth"]; [params setValue:@"click" forKey:@"riskType"]; // 指定智能点击形式验证，需与后端配置一致 [params setValue:@(1) forKey:@"hideSuccess"]; // 使用 NSNumber 表示布尔值 [params setValue:@"./gt4-loading.gif" forKey:@"loading"]; config.additionalParameter = params; GTCaptcha4Session *captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; ...
              
              #define captchaID @"1234567890abcdef"

GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];

NSMutableDictionary *params = [@{} mutableCopy];
[params setValue:@(1.25)                  forKey:@"rem"]; // 放大 1.25 倍
[params setValue:@[@"close", @"refresh"]  forKey:@"hideBar"]; // 隐藏关闭按钮及刷新按钮
[params setValue:@"300px"                 forKey:@"nextWidth"];
[params setValue:@"click"                 forKey:@"riskType"]; // 指定智能点击形式验证，需与后端配置一致
[params setValue:@(1)                     forKey:@"hideSuccess"]; // 使用 NSNumber 表示布尔值
[params setValue:@"./gt4-loading.gif"     forKey:@"loading"];

config.additionalParameter = params;

GTCaptcha4Session *captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
...
此代码块在浮窗中显示

defaultConfiguration

获得一个默认配置。

Declaration

+ (GTCaptcha4SessionConfiguration *)defaultConfiguration;
              
              + (GTCaptcha4SessionConfiguration *)defaultConfiguration;
此代码块在浮窗中显示

Return Value

+ (GTCaptcha4SessionConfiguration *)defaultConfiguration { GTCaptcha4SessionConfiguration *config = [[GTCaptcha4SessionConfiguration alloc] init]; config.debugEnable = NO; config.timeout = 8.0; config.language = [GTC4Utils systemLanguage]; config.protocol = @"https"; config.userInterfaceStyle = GTC4UserInterfaceStyleDefault; config.backgroundColor = [UIColor clearColor]; config.backgroundUserInteractionEnable = YES; return config; } 
              
              + (GTCaptcha4SessionConfiguration *)defaultConfiguration {
    GTCaptcha4SessionConfiguration *config = [[GTCaptcha4SessionConfiguration alloc] init];
    config.debugEnable  = NO;
    config.timeout      = 8.0;
    config.language     = [GTC4Utils systemLanguage];
    config.protocol     = @"https";
    config.userInterfaceStyle = GTC4UserInterfaceStyleDefault;
    config.backgroundColor = [UIColor clearColor];
    config.backgroundUserInteractionEnable = YES;
    
    return config;
}
此代码块在浮窗中显示

Error

错误描述对象

/// 不合法的参数。请检查输入的参数。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeInvalidParameter; /// 操作失败。详细查看描述。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeOperationFail; /// 资源缺失。请检查 GTCaptcha4.bundle 文件是否完整。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeMissedResource; /// 用户取消了验证。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeUserDidCancel; /// 加载文件失败。请检查是否导入了完整的 GTCaptcha4.bundle 文件或者配置的远程静态资源是否可访问。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeLoadFileFailure; /// 加载超时。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeTimeout; /// 执行 Javascript 脚本失败。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeEvaluatingJavascriptFail; /// Javascript 返回错误。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeJavascriptError; /// WebView 内存警告。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeWebViewMemoryWarning; /// 未知错误。 FOUNDATION_EXPORT NSString * const GTC4ErrorCodeUnknown;
              
              /// 不合法的参数。请检查输入的参数。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeInvalidParameter;
/// 操作失败。详细查看描述。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeOperationFail;
/// 资源缺失。请检查 GTCaptcha4.bundle 文件是否完整。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeMissedResource;

/// 用户取消了验证。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeUserDidCancel;

/// 加载文件失败。请检查是否导入了完整的 GTCaptcha4.bundle 文件或者配置的远程静态资源是否可访问。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeLoadFileFailure;
/// 加载超时。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeTimeout;
/// 执行 Javascript 脚本失败。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeEvaluatingJavascriptFail;
/// Javascript 返回错误。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeJavascriptError;
/// WebView 内存警告。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeWebViewMemoryWarning;

/// 未知错误。
FOUNDATION_EXPORT NSString * const GTC4ErrorCodeUnknown;
此代码块在浮窗中显示

code

错误码。可用于匹配处理。

Declaration

@property (readonly, nonatomic, strong) NSString *code;
              
              @property (readonly, nonatomic, strong) NSString *code;
此代码块在浮窗中显示

Seealso

见上方错误码清单

msg

错误信息。可用于用户界面展示。

Declaration

@property (readonly, nonatomic, strong) NSString *msg;
              
              @property (readonly, nonatomic, strong) NSString *msg;
此代码块在浮窗中显示

desc

错误详细描述。用于详细排查问题。

Declaration

@property (readonly, nonatomic, strong) NSDictionary *desc;
              
              @property (readonly, nonatomic, strong) NSDictionary *desc;
此代码块在浮窗中显示

Discussion

可用于支撑用户使用验证的运营问题。

icon
联系销售