Geetest GT4

https://docs.geetest.com/gt4
Admin
Geetest GT4 is a behavioral verification platform that provides interactive security services...
Tokens:45,443
Snippets:506
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Verification Flow Example

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Complete example showing configuration, client initialization, and verification execution.

```typescript
onClick(() => {  
    gtCaptcha4Config: GTCaptcha4Config =  new GTCaptcha4Config()  
            .setIsDebug(false) // TODO 线上务必关闭  
            .setLanguage("zh")  
            .setTimeOut(10000)  
            .setIsCanceledOnTouchOutside(true);  
    gtCaptcha4Client: GTCaptcha4Client = GTCaptcha4Client.getClient()  
            .init("your captcha_id", config)  
            .addOnSuccessListener({  
            async onSuccess(status: boolean, response: string) {  
              AlertDialog.show({ message: response })  
                if(status){  
                    // TODO 开启二次验证  
                }else {  
                    // TODO 用户答案验证错误  
                }  
            }  
          })  
           .addOnFailureListener({  
             onFailure: function (error: string) {  
               console.log('onFailure' + error);  
             }  
          })  
           .addOnWebViewShowListener({  
             onWebViewShow: function () {  
               console.log(`onWebViewShow`);  
             }  
          })  
           .verifyWithCaptcha();  
})
```

--------------------------------

### Loading Failure Response Example

Source: https://docs.geetest.com/gt4/apirefer/api/android

Example JSON response for a loading failure.

```json
{"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
```

--------------------------------

### Implement Verification Callbacks

Source: https://docs.geetest.com/gt4/deploy/client/android

Example implementation of success, failure, and WebView show listeners.

```java
gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {  
    @Override  
    public void onSuccess(boolean status, String response) {  
        if(status){  
            // TODO 开启二次验证  
        }else {  
            // TODO 用户答案验证错误  
        }  
    }  
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {  
    @Override  
    public void onFailure(String error) {  
    }  
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {  
      @Override  
      public void onWebViewShow() {  
      }  
  })
```

--------------------------------

### verify

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Starts the verification process for the current session.

```APIDOC
## - (void)verify;

### Description
Initiates the verification process.
```

--------------------------------

### Preload and normal loading patterns

Source: https://docs.geetest.com/gt4/deploy/client/android

Examples for initializing the captcha client with GTCaptcha4Config and handling success/failure callbacks.

```java
@Override  
public void onViewCreated(View view, Bundle savedInstanceState){  
    super.onViewCreated(view, savedInstanceState);  
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()  
            .setDebug(true) // TODO 线上务必关闭  
            .setLanguage("zh")  
            .setTimeOut(10000)  
            .setCanceledOnTouchOutside(true)  
            .build();  
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)  
            .init("your captcha_id", config);  
}  
  
private void click(){  
    gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {  
                @Override  
                public void onSuccess(boolean status, String response) {  
                    if(status){  
                        // TODO 开启二次验证  
                    }else {  
                        // TODO 用户答案验证错误  
                    }  
                }  
            })  
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {  
                @Override  
                public void onFailure(String error) {  
                }  
            })  
            .verifyWithCaptcha();  
}  
```

```java
private void click(){  
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()  
            .setDebug(true) // TODO 线上务必关闭  
            .setLanguage("zh")  
            .setTimeOut(10000)  
            .setCanceledOnTouchOutside(true)  
            .build();  
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)  
            .init("your captcha_id", config)  
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {  
                @Override  
                public void onSuccess(boolean status, String response) {  
                    if(status){  
                        // TODO 开启二次验证  
                    }else {  
                        // TODO 用户答案验证错误  
                    }  
                }  
            })  
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {  
                @Override  
                public void onFailure(String error) {  
                }  
            })  
            .verifyWithCaptcha();  
}  
```

--------------------------------

### GTCaptcha4Client Success Response Example

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Example JSON structure returned upon successful verification.

```json
{"lot_number":"b150e61198924eff9eaae121e9b67aa8","pass_token":"6fcfba4c35cb57b873c99c5b3b02089c58a26244c18f7706aaa1e87aed3aa8f4","gen_time":"1622020720","captcha_output":"Tu6rW0dRNO0NLxMKftwdH00G5whF5HHddthoXSEA1G4="}
```

--------------------------------

### verifyWithCaptcha

Source: https://docs.geetest.com/gt4/deploy/client/android

Starts the verification process.

```APIDOC
## public void verifyWithCaptcha()

### Description
Triggers the verification flow for the user.
```

--------------------------------

### Directory Structure for Custom Components

Source: https://docs.geetest.com/gt4/deploy/client/miniprogram/uniapp

Example directory structure for placing native custom components in a UniApp project.

```text
┌─swancomponents                百度小程序自定义组件存放目录  
│   └──captcha4                 百度小程序自定义组件  
│        ├─captcha4.js  
│        ├─captcha4.swan  
│        ├─captcha4.json  
│        └─captcha4.css  
├─pages  
│  └─index  
│        └─index.vue  
│  
├─static  
├─main.js  
├─App.vue  
├─manifest.json  
└─pages.json  
```

--------------------------------

### Handle Verification Callbacks

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Example implementation of success, failure, and webview show listeners.

```typescript
this.gtCaptcha4Client.addOnSuccessListener({  
  async onSuccess(status: boolean, response: string) {  
    if(status){  
      // TODO 开启二次验证  
    }else {  
      // TODO 用户答案验证错误  
    }  
  }  
})  
  .addOnFailureListener({  
    onFailure: function (error: string) {  
      console.log('onFailure' + error);  
    }  
  })  
  .addOnWebViewShowListener({  
    onWebViewShow: function () {  
      console.log(`onWebViewShow`);  
    }  
  })  
```

--------------------------------

### Example Usage of Additional Parameters

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Demonstrates how to populate and set additional parameters for a captcha session.

```Objective-C
#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];  
...
```

--------------------------------

### GTCaptcha4Client Loading Failure Example

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Example JSON structure for a loading failure, including user cancellation.

```json
{"code":"-34460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
```

--------------------------------

### Python Server-Side Integration Example

Source: https://docs.geetest.com/gt4/apirefer/api/server

Demonstrates how to initialize parameters, generate a HMAC-SHA256 signature, and perform the secondary validation request to the Geetest API.

```python
def post(self):  
    # 1.初始化极验参数信息  
    captcha_id = '647f5ed2ed8acb4be36784e01556bb71'  
    captcha_key = 'b09a7aafbfd83f73b35a9b530d0337bf'  
    api_server = 'http://gcaptcha4.geetest.com'  
  
    # 2.获取用户验证后前端传过来的验证参数  
    lot_number = self.get_argument('lot_number', '')  
    captcha_output = self.get_argument('captcha_output', '')  
    pass_token = self.get_argument('pass_token', '')  
    gen_time = self.get_argument('gen_time', '')  
  
    # 3.生成签名  
    # 生成签名使用标准的hmac算法，使用用户当前完成验证的流水号lot_number作为原始消息message，使用客户验证私钥作为key  
    # 采用sha256散列算法将message和key进行单向散列生成最终的签名  
    lotnumber_bytes = lot_number.encode()  
    prikey_bytes = captcha_key.encode()  
    sign_token = hmac.new(prikey_bytes, lotnumber_bytes, digestmod='SHA256').hexdigest()  
  
    # 4.上传校验参数到极验二次验证接口, 校验用户验证状态  
    query = {  
        "lot_number": lot_number,  
        "captcha_output": captcha_output,  
        "pass_token": pass_token,  
        "gen_time": gen_time,  
        "sign_token": sign_token,  
    }  
    # captcha_id 参数建议放在 url 后面, 方便请求异常时可以在日志中根据id快速定位到异常请求  
    url = api_server + '/validate' + '?captcha_id={}'.format(captcha_id)  
    # 注意处理接口异常情况，当请求极验二次验证接口异常或响应状态非200时做出相应异常处理  
    # 保证不会因为接口请求超时或服务未响应而阻碍业务流程  
    try:  
        res = requests.post(url, query)  
        assert res.status_code == 200  
        gt_msg = json.loads(res.text)  
    except Exception as e:  
        gt_msg = {'result': 'success', 'reason': 'request geetest api fail'}  
      
    # 5.根据极验返回的用户验证状态, 网站主进行自己的业务逻辑  
    if gt_msg['result'] == 'success':  
        self.write({'login': 'success', 'reason': gt_msg['reason']})  
    else:  
        self.write({'login': 'fail', 'reason': gt_msg['reason']})  
```

--------------------------------

### Start Verification

Source: https://docs.geetest.com/gt4/deploy/client/android

Triggers the verification flow.

```java
public void verifyWithCaptcha();
```

--------------------------------

### Get Default Configuration

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Retrieves a default configuration instance.

```Objective-C
+ (GTCaptcha4SessionConfiguration *)defaultConfiguration;
```

```Objective-C
+ (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;  
}
```

--------------------------------

### GTCaptcha4Client Failure Response Example

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Example JSON structure returned when verification fails.

```json
{"captchaId":"647f5ed2ed8acb4be36784e01556bb71","captchaType":"slide","challenge":"95ed53b4-95c6-4c6b-9aac-769b29ef74a0"}
```

--------------------------------

### Start Verification

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Initiates the verification flow. Ensure init() and necessary listeners are configured before calling this method.

```TypeScript
public verifyWithCaptcha(): GTCaptcha4Client
```

--------------------------------

### Get Version

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Returns the current version string of the SDK.

```TypeScript
public static getVersion(): string
```

--------------------------------

### Initialize and Verify Geetest GT4 on Android

Source: https://docs.geetest.com/gt4/quick_integration_guide

Shows the configuration, initialization, and verification listener setup for Android native applications.

```java
GTCaptcha4Config config = new GTCaptcha4Config.Builder()  
    .setDebug(false)  
    .setLanguage("zh")  
    .setTimeOut(10000)  
    .setCanceledOnTouchOutside(true)  
    .build();  
  
gtCaptcha4Client = GTCaptcha4Client.getClient(activity)  
    .init("your captcha_id", config)  
    .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {  
      @Override  
      public void onSuccess(boolean status, String response) {  
        if (status) {  
          // 提交 response 到业务服务端二次校验  
        } else {  
          // 用户答案验证错误  
        }  
      }  
    })  
    .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {  
      @Override  
      public void onFailure(String error) {  
        // 记录 error，展示错误码  
      }  
    });  
  
gtCaptcha4Client.verifyWithCaptcha();  
```

--------------------------------

### Example result dictionary

Source: https://docs.geetest.com/gt4/apirefer/api/ios

A sample structure of the result dictionary returned by the verification session.

```JSON
{
	pass_token = "eb6d2e064524ae96ddc99a0e6e15f95dbb234008d108f0db269f27d426bcf3c6";
	gen_time = "1660894030";
	captcha_output = "fI9I34MDjVi10gJO_EqXwNpN8hK0rYLEPVWSDE4W6kc1umDoTHIlD_t6YQNNpPG2tJlKR8he6WFWkkllU8goGeNVNOzhqmAm256BpK8qAEHNrOjHzkNagfIcx_A21ssPrG6YlnnHFx3PfBnbrn5fb2aKDIi0I5xmCUjxq0dsFuANLIQVtllMjkJ7-1l_j-Wz";
	captcha_id = "647f5ed2ed8acb4be36784e01556bb71";
	lot_number = "0861c607d519469b9117d0c6dd551fe3";
}
```

--------------------------------

### Verify with Captcha

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Start the verification process.

```typescript
public void verifyWithCaptcha();  
```

--------------------------------

### Alipay Component Implementation

Source: https://docs.geetest.com/gt4/deploy/client/miniprogram/uniapp

Example of the captcha component tag for Alipay integration.

```html
<captcha4  
  id="captcha"  
  v-if="loadCaptcha"  
  :captchaId="captchaId"  
  onSuccess="captchaSuccess"  
/>  
```

--------------------------------

### Get SDK version

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Retrieve the current version string of the SDK.

```objective-c
+ (NSString *)sdkVersion;
```

--------------------------------

### Control Verification Flow

Source: https://docs.geetest.com/gt4/apirefer/api/android

Methods to start or cancel the verification process. Ensure init and listeners are set before calling these.

```java
public GTCaptcha4Client verifyWithCaptcha()
```

```java
public void cancel()
```

--------------------------------

### Secondary Validation API Response Examples

Source: https://docs.geetest.com/gt4/deploy/server

Examples of JSON responses from the secondary validation API for successful, failed, and erroneous requests.

```json
{
    "status": "success", // 请求状态
    "result": "success", // 二次校验结果
    "reason": "", // 校验结果说明
    "captcha_args": { // 验证输出参数
        "used_type": "slide",
        "user_ip": "127.0.0.1",
        "lot_number": "4dc3cfc2cdff448cad8d13107198d473",
        "scene": "反爬虫",
        "referer": "http://127.0.0.1:8077/"
        // ...
    }
}
```

```json
{
    "status": "success", // 请求状态
    "result": "fail", // 二次校验结果
    "reason": "pass_token expire", // 校验结果说明
    "captcha_args": { // 验证输出参数
        ...
    }
}
```

```json
{
    "status": "error", // 请求状态
    "code": "-50005", // 错误码
    "msg": "illegal gen_time", // 错误信息
    "desc": { // 错误描述
        "type": "defined error"
    }
}
```

--------------------------------

### Initialize GTCaptcha4Client on HarmonyOS

Source: https://docs.geetest.com/gt4/compliance

Demonstrates the configuration and client initialization for HarmonyOS, including listeners for success, failure, and webview display events.

```typescript
onClick(() => {  
    gtCaptcha4Config: GTCaptcha4Config =  new GTCaptcha4Config()  
            .setIsDebug(false) // TODO 线上务必关闭  
            .setLanguage("zh")  
            .setTimeOut(10000)  
            .setIsCanceledOnTouchOutside(true);  
    gtCaptcha4Client: GTCaptcha4Client = GTCaptcha4Client.getClient()  
            .init("your captcha_id", config)  
            .addOnSuccessListener({  
            async onSuccess(status: boolean, response: string) {  
              AlertDialog.show({ message: response })  
                if(status){  
                    // TODO 开启二次验证  
                }else {  
                    // TODO 用户答案验证错误  
                }  
            }  
          })  
           .addOnFailureListener({  
             onFailure: function (error: string) {  
               console.log('onFailure' + error);  
             }  
          })  
           .addOnWebViewShowListener({  
             onWebViewShow: function () {  
               console.log(`onWebViewShow`);  
             }  
          })  
           .verifyWithCaptcha();  
})  
```

--------------------------------

### Manage Lifecycle and Configuration

Source: https://docs.geetest.com/gt4/apirefer/api/android

Methods for handling logging, resource destruction, and configuration changes like screen rotation.

```java
public void setLogEnable(boolean enable)
```

```java
public void destroy()
```

```java
public void configurationChanged(Configuration newConfig)
```

--------------------------------

### GTCaptcha4Client.init

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Initializes the SDK with the provided captchaId and optional configuration.

```APIDOC
## GTCaptcha4Client.init(captchaId: string, config?: GTCaptcha4Config)

### Description
Initializes the verification client with the required captchaId and optional configuration object.

### Parameters
- **captchaId** (string) - Required - The APP_ID obtained from the Geetest dashboard.
- **config** (GTCaptcha4Config) - Optional - Configuration object for the verification process.
```

--------------------------------

### Initialize GTCaptcha4Client

Source: https://docs.geetest.com/gt4/deploy/client/android

Methods for initializing the SDK client. It is recommended to call these in onCreate or onCreateView to enable preloading.

```java
public static GTCaptcha4Client getClient(Context context);  
public GTCaptcha4Client init(String captchaId);  
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
```

--------------------------------

### Initialize SDK Client

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Methods for initializing the GTCaptcha4Client.

```typescript
public static getClient(context: UIContext): GTCaptcha4Client;  
public init(captchaId: string, config?: GTCaptcha4Config): GTCaptcha4Client;  
```

--------------------------------

### Control GTCaptcha4Session lifecycle

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Methods to start or cancel the verification process.

```objective-c
- (void)verify;
```

```objective-c
- (void)cancel;
```

--------------------------------

### Handle Verification Errors

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Example of processing errors within the failure listener.

```typescript
gtCaptcha4Client.addOnFailureListener({  
  onFailure: function (error: string) {  
    // 返回error内容示例  
    // {"code":"-34460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}  
    // 可对error做json解析，自行替换错误描述，保留错误码  
  }  
})  
```

--------------------------------

### initGeetest4(config, callback)

Source: https://docs.geetest.com/gt4/apirefer/api/web

Initializes the Geetest GT4 verification instance. The config object accepts various parameters to customize the behavior and appearance of the verification widget.

```APIDOC
## initGeetest4(config, callback)

### Description
Initializes the Geetest GT4 verification instance with the provided configuration object.

### Parameters
#### config (Object) - Required
- **captchaId** (string) - Required - The verification ID obtained from the Geetest dashboard.
- **product** (string) - Optional - The display form: 'float', 'popup', or 'bind'. Default: 'float'.
- **nativeButton** (object) - Optional - Customizes the button style (width, height).
- **rem** (number) - Optional - Scaling ratio for the verification widget. Default: 1.
- **language** (string) - Optional - Language for the interface (e.g., 'zho', 'eng'). Default: 'zho'.
- **protocol** (string) - Optional - Protocol header ('http://' or 'https://').
- **timeout** (number) - Optional - Request timeout in milliseconds. Default: 30000.
- **hideBar** (array) - Optional - Elements to hide (e.g., ['close', 'refresh']).
- **mask** (object) - Optional - Popup configuration (outside click behavior, background color).
- **apiServers** (array) - Optional - API request endpoints.
- **nextWidth** (string) - Optional - Fixed width for the popup.
- **riskType** (string) - Optional - Specifies verification form for risk scenarios.
- **hideSuccess** (boolean) - Optional - Hides success popup for 'bind' mode.
- **offlineCb** (function) - Optional - Custom handler for offline/fallback mode.
- **onError** (function) - Optional - Error handler for initialization failures.
- **userInfo** (string) - Optional - Client-side user information (e.g., username, email).

### Example
```javascript
initGeetest4({
    captchaId: 'your_captcha_id',
    product: 'popup',
    language: 'eng'
}, function (captchaObj) {
    captchaObj.appendTo("#captchaBox");
});
```
```

--------------------------------

### Handle Ready Event

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/my

Listens for the completion of the verification button DOM generation.

```javascript
// axml  
<captcha4  onReady="captchaReady"/>  
//js  
captchaReady:function(){  
    console.log('captcha-Ready!')  
}
```

--------------------------------

### GTCaptcha4Client Initialization

Source: https://docs.geetest.com/gt4/deploy/client/android

Methods to initialize the GTCaptcha4 client. It is recommended to call these in onCreate or onCreateView for faster verification startup.

```APIDOC
## public static GTCaptcha4Client getClient(Context context)
## public GTCaptcha4Client init(String captchaId)
## public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

### Description
Initializes the SDK configuration. The context must be an Activity instance.

### Parameters
- **context** (Context) - Required - The application context, must be an Activity instance.
- **captchaId** (String) - Required - The APP_ID obtained from the Geetest dashboard.
- **config** (GTCaptcha4Config) - Optional - Configuration object for the verification process.
```

--------------------------------

### Trigger Verification

Source: https://docs.geetest.com/gt4/deploy/client/ios

Call the verify method on the session instance to start the captcha process.

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

--------------------------------

### Listen to Ready Event

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/ks

Handle the event triggered when the verification button DOM is generated.

```javascript
// ksml  
<captcha4  bindReady="captchaReady"/>  
//js  
captchaReady:function(){
    console.log('captcha-Ready!')  
}
```

--------------------------------

### Utility Methods

Source: https://docs.geetest.com/gt4/apirefer/api/android

Utility methods to retrieve the SDK version and check for WebView support.

```java
public static String getVersion()
```

```java
public static Pair<Boolean, String> isSupportWebView(Context context)
```

--------------------------------

### Get GTCaptcha4Client Instance

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Retrieves the GTCaptcha4Client object. This is not a singleton, so the returned instance should be stored for use throughout the Page lifecycle.

```TypeScript
public static getClient(context UIContext): GTCaptcha4Client
```

--------------------------------

### Listen for Ready Events

Source: https://docs.geetest.com/gt4/apirefer/api/web

onReady and onNextReady allow developers to hook into the captcha loading lifecycle.

```html
<div id="captcha-box">  
    <div id="loading-tip">加载中，请稍后...</div>  
</div>  
<script>  
    initGeetest4({  
        // 省略配置参数  
    }, function (captchaObj) {  
        captchaObj.appendto('#captcha-box');  
  
        // 省略其他方法的调用  
  
        captchaObj.onReady(function () {  
            // DOM 准备好后，隐藏 #loading-tip 元素  
            // 仅作示例用，用您适合的方式隐藏即可  
            document.getElementById('loading-tip').style.display = 'none';  
        });  
    });  
</script>  
```

```html
<div id="captcha-box">  
    <div id="loading-tip">加载中，请稍后...</div>  
</div>  
<script>  
    initGeetest4({  
        // 省略配置参数  
    }, function (captchaObj) {  
        captchaObj.appendto('#captcha-box');  
  
        // 省略其他方法的调用  
  
        captchaObj.onNextReady(function () {  
              
        });  
    });  
</script>  
```

--------------------------------

### Integrate Validation into Business Logic

Source: https://docs.geetest.com/gt4/quick_integration_guide

Example of using the validation function within an Express route handler to protect sensitive operations.

```javascript
app.post("/api/save-config", async (req, res) => {  
  try {  
    const gt = await validateGeeTest4({  
      captchaId: process.env.GEETEST_CAPTCHA_ID,  
      captchaKey: process.env.GEETEST_CAPTCHA_KEY,  
      lot_number: req.body.lot_number,  
      captcha_output: req.body.captcha_output,  
      pass_token: req.body.pass_token,  
      gen_time: req.body.gen_time  
    });  
  
    if (gt.result !== "success") {  
      return res.status(403).json({  
        result: "fail",  
        reason: gt.reason || gt.msg || "captcha validate failed",  
        code: gt.code  
      });  
    }  
  
    // 在这里执行真实业务，例如保存配置、登录、提交订单。  
    return res.json({ result: "success" });  
  } catch (error) {  
    // 高风险动作建议失败关闭：极验接口异常时拒绝业务。  
    return res.status(503).json({  
      result: "fail",  
      reason: "captcha service unavailable"  
    });  
  }  
});  
```

--------------------------------

### Initialize GTCaptcha4Client on Android

Source: https://docs.geetest.com/gt4/compliance

Shows the configuration and initialization of the GTCaptcha4Client, including success and failure listeners for handling verification results.

```java
private void click(){  
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()  
            .setDebug(true) // TODO 线上务必关闭  
            .setLanguage("zh")  
            .setTimeOut(10000)  
            .setCanceledOnTouchOutside(true)  
            .build();  
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)  
            .init("your captcha_id", config)  
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {  
                @Override  
                public void onSuccess(boolean status, String response) {  
                    if(status){  
                        // TODO 开启二次验证  
                    }else {  
                        // TODO 用户答案验证错误  
                    }  
                }  
            })  
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {  
                @Override  
                public void onFailure(String error) {  
                }  
            })  
            .verifyWithCaptcha();  
}  
```

--------------------------------

### Geetest Secondary Validation Response Examples

Source: https://docs.geetest.com/gt4/apirefer/api/server

JSON response structures for successful validation, failed validation, and system error scenarios.

```json
// 校验成功返回示例  
{  
    "result": "success",   
    "reason": "",   
    "captcha_args": {  
        "used_type": "slide",   
        "user_ip": "127.0.0.1",   
        "lot_number": "4dc3cfc2cdff448cad8d13107198d473",   
        "scene": "反爬虫",   
        "referer": "http://127.0.0.1:8077/"  
    }  
}  
  
// 校验失败返回示例  
{  
    "result": "fail",   
    "reason": "pass_token expire",   
    "captcha_args": {  
        ...  
    }  
}  
  
// 请求异常返回示例  
{  
    "status": "error",   
    "code": "-50005",   
    "msg": "illegal gen_time",   
    "desc": {  
        "type": "defined error"  
    }  
}  
```

--------------------------------

### Configure Kotlin in Module build.gradle

Source: https://docs.geetest.com/gt4/deploy/client/android

Apply the Kotlin plugin and add the standard library dependency in the module-level build.gradle file.

```gradle
apply plugin: 'kotlin-android'  
dependencies {  
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"  
}  
```

--------------------------------

### Get GTCaptcha4Client Instance

Source: https://docs.geetest.com/gt4/apirefer/api/android

Retrieves the GTCaptcha4Client instance. Note that this is not a singleton, so the returned object should be stored for use in lifecycle methods like onDestroy.

```java
public static GTCaptcha4Client getClient(Context context)
```

--------------------------------

### Set Resource Path

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Defines the webView resource loading path.

```typescript
setResourcePath(html: string): GTCaptcha4Config  
```

--------------------------------

### Configure SDK Dependency

Source: https://docs.geetest.com/gt4/deploy/client/harmonyos

Add the SDK dependency to the oh-package.json5 file after importing the .har file.

```json
"dependencies": {  
    "@geetest/captcha": "file:./libs/geetest_captcha_harmonyos_vx.y.z_date.har"  
}  
```

--------------------------------

### Initialize Geetest GT4

Source: https://docs.geetest.com/gt4/deploy/client/web

Initialize the verification instance using your captchaId and append it to a specific DOM element.

```javascript
initGeetest4({  
    captchaId: '您的captchaId'  
},function (captcha) {  
    // captcha为验证码实例  
    captcha.appendTo("#captcha");// 调用appendTo将验证码插入到页的某一个元素中，这个元素用户可以自定义  
});
```

--------------------------------

### Configure custom loading path

Source: https://docs.geetest.com/gt4/faq/android

Use setParams to specify a local path for a custom loading animation resource.

```java
Map<String, Object> params = new HashMap<>();  
params.put("loading", "./loading.gif");  
GTCaptcha4Config builder = new GTCaptcha4Config.Builder()  
    .setParams(params);  
```

--------------------------------

### Syntax Conversion Note

Source: https://docs.geetest.com/gt4/deploy/client/miniprogram/uniapp

Summary of syntax changes required when migrating from native mini-program templates to Vue-style bindings.

```text
属性绑定从 captchaId="{{captchaId}}" ，改为 :captchaId="captchaId" , wx:if 改为 v-if  
```

--------------------------------

### MiniProgram Configuration Parameters

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/my

Configuration parameters for the captcha4 component.

```APIDOC
## Configuration Parameters

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| captchaId | Y | string | - | 验证码 ID |
| language | N | string | zh | 语言 (zh - 中文，en - 英文) |
| offline | N | boolean | false | 强制宕机模式 |
| useNativeButton | N | boolean | true | 是否使用唤醒按钮 |
| riskType | N | string | - | 指定验证形式 |
| hideBar | N | array | [] | 隐藏后续验证界面的关闭按钮、刷新按钮 |
| mask | N | object | {outside:true, bgColor:'#0000004d'} | 弹窗相关配置项 |
| hideSuccess | N | boolean | false | 是否隐藏 bind 模式下的成功弹窗 |
```

--------------------------------

### Configure Language

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Sets the language, defaulting to the system language.

```Objective-C
@property (nonatomic, strong) NSString *language;
```

--------------------------------

### Configure Resource Path

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Sets the full path for remote static resources.

```Objective-C
@property (nullable, nonatomic, strong) NSString *resourcePath;
```

--------------------------------

### Include Geetest GT4 Script

Source: https://docs.geetest.com/gt4/deploy/client/web

Add the gt4.js library to your web page to enable the initialization function.

```html
<script src="gt4.js"></script>
```

--------------------------------

### Initialize and Verify Geetest GT4 on iOS

Source: https://docs.geetest.com/gt4/quick_integration_guide

Demonstrates the implementation of GTCaptcha4SessionTaskDelegate and the verification flow for iOS native applications.

```objective-c
#import <GTCaptcha4/GTCaptcha4.h>  
  
#define captchaID @"你的 captchaId"  
  
@interface ViewController () <GTCaptcha4SessionTaskDelegate>  
@property (nonatomic, strong) GTCaptcha4Session *captchaSession;  
@end  
  
- (GTCaptcha4Session *)captchaSession {  
  if (!_captchaSession) {  
    _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID];  
    _captchaSession.delegate = self;  
  }  
  return _captchaSession;  
}  
  
- (void)viewDidLoad {  
  [super viewDidLoad];  
  [self captchaSession];  
}  
  
- (void)startVerify {  
  [self.captchaSession verify];  
}  
  
- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession  
              didReceive:(NSString *)code  
                  result:(NSDictionary *)result {  
  if ([@"1" isEqualToString:code] && result.count > 0) {  
    // 提交 result 到业务服务端二次校验  
  }  
}  
  
- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession  
         didReceiveError:(GTC4Error *)error {  
  NSLog(@"captcha error: %@", error.description);  
}  
```

--------------------------------

### GTCaptcha4Config.build()

Source: https://docs.geetest.com/gt4/apirefer/api/android

Constructs a GTCaptcha4Config object to be used with the init() interface.

```APIDOC
## GTCaptcha4Config.build()

### Description
Constructs a GTCaptcha4Config object, which is required for initializing the captcha client.

### Declaration
`public GTCaptcha4Config build()`
```

--------------------------------

### Initialize Popup Verification

Source: https://docs.geetest.com/gt4/apirefer/api/web

Configures the verification widget to display in a popup format.

```javascript
initGeetest4({  
    // 省略必须的配置参数  
  
    product: 'popup'  
}, function (captchaObj) {  
    captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内  
    captchaObj.onReady(function(){
      //your code  
    }).onSuccess(function(){
      //your code  
    }).onError(function(){
      //your code  
    })  
})
```

--------------------------------

### 服务端二次校验异常处理

Source: https://docs.geetest.com/gt4/bypass

在服务端二次校验接口中添加异常捕获，当请求极验接口失败或状态码非200时，手动返回成功结果以保障业务流程不被阻断。

```python
try:  
    res = requests.post(url, query)  
    assert res.status_code == 200  
    gt_msg = json.loads(res.text)  
except Exception as e:  
    gt_msg = {'result': 'success', 'reason': 'request geetest api fail'}  
```

--------------------------------

### Initialize GTCaptcha4Session instances

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Factory and instance methods to create a new session with a captcha ID and optional configuration.

```objective-c
+ (instancetype)sessionWithCaptchaID:(NSString *)captchaID;
```

```objective-c
+ (instancetype)sessionWithCaptchaID:(NSString *)captchaID
                       configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
```

```objective-c
- (instancetype)initWithCaptchaID:(NSString *)captchaID;
```

```objective-c
- (instancetype)initWithCaptchaID:(NSString *)captchaID
                    configuration:(nullable GTCaptcha4SessionConfiguration *)configuration;
```

--------------------------------

### 在 app.json 中声明插件

Source: https://docs.geetest.com/gt4/deploy/client/miniprogram/my

在项目配置文件中引入极验插件，provider 为固定插件 ID。

```json
{
  "plugins": {
    "captcha4": {
      "version": "*", // 目前只支持设置 * 拉取当前上架最新版本
      "provider": "2021002178617823"
    }
  }
}
```

--------------------------------

### Initialize Geetest Verification

Source: https://docs.geetest.com/gt4/quick_integration_guide

Initialize the verification object and define event handlers for success, failure, and errors.

```javascript
<div id="captcha-box"></div>

<script>
  let captchaObj = null;
  let captchaReady = false;

  initGeetest4(
    {
      captchaId: "你的 captchaId",
      product: "bind",
      language: "zho",
      timeout: 10000,
      protocol: "https://"
    },
    function (captcha) {
      captchaObj = captcha;

      captcha
        .onReady(function () {
          captchaReady = true;
        })
        .onSuccess(function () {
          const result = captchaObj.getValidate();
          if (!result) return;

          submitBusinessWithCaptcha(result);
        })
        .onFail(function (failObj) {
          console.warn("captcha fail", failObj);
        })
        .onError(function (error) {
          console.error("captcha error", error);
          alert("验证加载异常，请刷新页面后重试");
        })
        .onClose(function () {
          alert("请完成验证后继续操作");
        });
    }
  );
</script>
```

--------------------------------

### Configure User Interface Style

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Sets the interface and status bar style.

```Objective-C
@property (nonatomic, assign) GTC4UserInterfaceStyle userInterfaceStyle;
```

--------------------------------

### Build GTCaptcha4Config

Source: https://docs.geetest.com/gt4/apirefer/api/android

Constructs the configuration object required for the init interface.

```java
public GTCaptcha4Config build()
```

--------------------------------

### Configure Kotlin in Root build.gradle

Source: https://docs.geetest.com/gt4/deploy/client/android

Define the Kotlin version and plugin dependency in the root build.gradle file for non-Kotlin projects.

```gradle
ext.kotlin_version = "1.6.22"  
  
dependencies {  
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"  
}  
```

--------------------------------

### Configure custom loading animation

Source: https://docs.geetest.com/gt4/faq/ios

Use this configuration to enable custom loading behavior when the default loading animation is removed or replaced.

```objective-c
config.additionalParameter = [NSMutableDictionary dictionaryWithDictionary:@{@”loading”:@””}]
```

--------------------------------

### MiniProgram Methods

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/my

Methods to control the captcha instance.

```APIDOC
## Methods

- **showCaptcha()**: 显示验证窗。
- **reset()**: 重置验证码。
- **hiddenCaptcha()**: 关闭验证窗。
```

--------------------------------

### Add WebView Show Listener

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Registers a listener for when the verification frontend is successfully loaded.

```TypeScript
public addOnWebViewShowListener(listener: OnWebViewShowListener): GTCaptcha4Client
```

--------------------------------

### Initialize Geetest GT4

Source: https://docs.geetest.com/gt4/apirefer/api/web

The initGeetest4 function initializes the captcha and provides a callback containing the captcha instance.

```javascript
initGeetest4({  
    // 省略配置参数  
}, function (captchaObj) {  
    // 现在可以调用验证实例 captchaObj 的方法了  
});  
```

--------------------------------

### Configure Additional Parameters

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Sets extra parameters to be submitted to the service.

```Objective-C
@property (nullable, nonatomic, strong) NSDictionary *additionalParameter;
```

--------------------------------

### Set Resource Path

Source: https://docs.geetest.com/gt4/apirefer/api/android

Sets the WebView resource path. Defaults to the assets directory.

```java
public Builder setResourcePath(String html)
```

--------------------------------

### Declare Alipay Mini Program Plugin

Source: https://docs.geetest.com/gt4/quick_integration_guide

Add the captcha4 plugin to the app.json file for Alipay.

```json
{
  "plugins": {
    "captcha4": {
      "version": "*",
      "provider": "2021002178617823"
    }
  }
}
```

--------------------------------

### onNextReady(callback)

Source: https://docs.geetest.com/gt4/apirefer/api/web

Registers a callback function to be executed when the next step resources are loaded.

```APIDOC
## onNextReady(callback)

### Description
Listens for the event when the resources for the next verification step are loaded.
```

--------------------------------

### defaultConfiguration

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Returns a default configuration instance for the captcha session.

```APIDOC
## + (GTCaptcha4SessionConfiguration *)defaultConfiguration

### Description
Creates and returns a new GTCaptcha4SessionConfiguration object initialized with default values for all properties.

### Return Value
- **GTCaptcha4SessionConfiguration**: An instance with default settings (debugEnable=NO, timeout=8.0, protocol=@"https", etc.).
```

--------------------------------

### Listen to Ready Event

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/qq

Registers a callback for when the CAPTCHA button DOM is ready.

```javascript
// qml  
<captcha4  onReady="captchaReady"/>  
//js  
captchaReady:function(){  
    console.log('captcha-Ready!')  
}
```

--------------------------------

### Initialize CAPTCHA

Source: https://docs.geetest.com/gt4/apirefer/api/android

Initializes the client with a captchaId. Calling this triggers the loading process; calling it before onResume allows for pre-loading.

```java
public GTCaptcha4Client init(String captchaId)
```

```java
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
```

--------------------------------

### onReady(callback)

Source: https://docs.geetest.com/gt4/apirefer/api/web

Registers a callback function to be executed when the verification button DOM is fully generated.

```APIDOC
## onReady(callback)

### Description
Listens for the event when the verification button DOM is ready.
```

--------------------------------

### GTCaptcha4Client onWebViewShow Declaration

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Defines the callback for when the verification frontend has successfully loaded.

```typescript
onWebViewShow: () => void;  
```

--------------------------------

### Import GTCaptcha4 Header

Source: https://docs.geetest.com/gt4/deploy/client/ios

Include the framework header in your project files to access the SDK classes.

```objective-c
#import <GTCaptcha4/GTCaptcha4.h>
```

--------------------------------

### Listen to Ready Event

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/tt

Handles the event triggered when the captcha button DOM is ready.

```javascript
// ttml  
<captcha4  onReady="captchaReady"/>  
//js  
captchaReady:function(){  
    console.log('captcha-Ready!')  
}
```

--------------------------------

### Listen to Ready Event

Source: https://docs.geetest.com/gt4/apirefer/api/miniprogram/qa

Handles the event triggered when the captcha button DOM is ready.

```javascript
// qxml  
<captcha4  bindReady="captchaReady"/>  
//js  
captchaReady:function(){  
    console.log('captcha-Ready!')  
}
```

--------------------------------

### Configure Background Color

Source: https://docs.geetest.com/gt4/apirefer/api/ios

Sets the background color, defaulting to transparent.

```Objective-C
@property (nonatomic, strong) UIColor *backgroundColor;
```

--------------------------------

### 执行二次验证

Source: https://docs.geetest.com/gt4/deploy/client/miniprogram/ks

将获取到的验证结果提交至用户服务端进行二次验证。

```javascript
captchaValidate: function(){
    var self = this;
    var data = self.data.result; // 获取完成验证码时存储的验证结果
    if(typeof data !== 'object'){
      console.log("请先完成验证！")
      return
    }
    // 将结果提交给用户服务端进行二次验证
    ks.request({
      url: "用户业务接口",
      method: 'POST',
      dataType: 'json',
      data: Object.assign({},data, {
        captcha_id: self.data.captchaId
      }),
      success: function (res) {
        ks.showToast({
          title: res.data.result
        })
      },
      fail: function () {
        console.log('error')
      }
    })
  }
```

--------------------------------

### Configure Gradle Repositories

Source: https://docs.geetest.com/gt4/deploy/client/android

Add the libs directory to the repositories block in your project's build.gradle file to locate the AAR file.

```gradle
repositories {  
    flatDir {  
        dirs 'libs'  
    }  
}  
```

--------------------------------

### Initialize GTCaptcha4Session

Source: https://docs.geetest.com/gt4/deploy/client/ios

Configure the session instance and register the captcha ID within your ViewController.

```objective-c
#define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  
  
@interface ViewController () <GTCaptcha4SessionTaskDelegate>  
  
@property (strong, nonatomic) IBOutlet UIButton *startBtn;  
  
@property (nonatomic, strong) GTCaptcha4Session *captchaSession;  
  
@end  
  
@implementation ViewController  
  
- (GTCaptcha4Session *)captchaSession {  
    if (!_captchaSession) {  
        _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID];  
        /// 如需修改默认配置  
        /// 可选择下面注释的方式创建实例  
        // GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];  
        // config.timeout = 8.0f;  
        // ...  
        // _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];  
          
        _captchaSession.delegate = self;  
    }  
      
    return _captchaSession;  
}  
  
- (void)viewDidLoad {  
    [super viewDidLoad];  
      
    // 提前初始化验证会话，如果不在此位置调用，将使用懒加载模式  
    [self captchaSession];  
      
    [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];  
}
```

--------------------------------

### Initialize Captcha

Source: https://docs.geetest.com/gt4/apirefer/api/harmonyos

Initializes the captcha client using a specific captchaId and configuration object.

```TypeScript
public init(captchaId: string, config: GTCaptcha4Config): GTCaptcha4Client
```

--------------------------------

### setLogEnable

Source: https://docs.geetest.com/gt4/deploy/client/android

Configures whether to print SDK logs for monitoring.

```APIDOC
## public void setLogEnable(boolean enable)

### Description
Enables or disables internal SDK log output.

### Parameters
- **enable** (boolean) - Required - True to enable logs, false to disable.
```
Tokens:
Raw