Android CAPTCHA Integration Guide

Product Introduction

Item	Description
Main Features	Next-generation CAPTCHA, intelligently addressing business losses and security risks caused by automated attacks from scripts.
SDK Privacy Policy	Policy
SDK Compliance Guide	Guide
SDK Download Link	Download

Environment Requirements

Item	Resource
Development Target	`Android 5.0+` (minSdk 21)
Development Environment	`Android Studio 2020.3.1 Arctic Fox+`
Build Tool	`Gradle` (Android Gradle Plugin 7+)
System Dependencies	None
`SDK` Third-party Dependencies	None
Package Increment	Verified `SDK`: `60K`

Integrating the `SDK`

Importing the `SDK`

Drag the .aar file (including engagelab_captcha_android_vx.y.z.aar) from the zip package into the libs folder of your project. After dragging the .aar file into the libs folder, ensure that the .aar file is added to the Library. Add the following code to the build.gradle file of the project:

repositories { flatDir { dirs 'libs' } }

              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

Additionally, manually add the aar package as a dependency (AAR does not automatically include third-party dependencies, so you need to add them manually):

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

              
              implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

このコードブロックはフローティングウィンドウ内に表示されます

Configuration for Non-`Kotlin` Projects

In the root directory build.gradle configuration:

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

              
              ext.kotlin_version = "1.6.22"

dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

このコードブロックはフローティングウィンドウ内に表示されます

In the module build.gradle configuration:

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

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

このコードブロックはフローティングウィンドウ内に表示されます

If there is a conflict with the kotlin version, exclude the kotlin dependency: exclude(group: 'org.jetbrains.kotlin')

`Adding Permissions`

<uses-permission android:name="android.permission.INTERNET" />  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

              
              <!--Required - Default application-->
<uses-permission android:name="android.permission.INTERNET" />
<!--Must be declared for compatibility with API levels below 23 (not included) (i.e., applications running on Android 4.x and 5.x need to declare this) - Default not applied-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

このコードブロックはフローティングウィンドウ内に表示されます

Proguard Rules

The SDK's aar package has already been obfuscated. Double obfuscation may lead to unexpected errors. By default, the aar package includes the current SDK's obfuscation configuration. Both remote dependencies and local aar dependencies ensure that the SDK is not obfuscated again. If you need to extract the aar package and separately integrate the jar and resource files, make sure to copy the contents of the proguard.txt file from the extracted directory into your application's obfuscation configuration to avoid double obfuscation of the SDK.

If you are using andRes for resource obfuscation, exclude the resources included in the SDK from obfuscation to avoid errors caused by missing resources. The exclusion configuration is as follows:

"R.string.gt4_*", "R.style.gt4_*",

              
              "R.string.gt4_*",
"R.style.gt4_*",

このコードブロックはフローティングウィンドウ内に表示されます

Interface Configuration

Call Logic

Configure Initialization
Start Verification
Get Verification Callback
Destroy Resources

Refer to the Product Structure Process for 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.

Initialization

SDK initialization configuration information can be placed in the onCreate or onCreateView method for initialization.

Method Description

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

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

このコードブロックはフローティングウィンドウ内に表示されます

Parameter Description

Parameter	Type	Description
`context`	`Context`	Context object, must be an `Activity` instance
`appId`	`String`	`APP_ID`, required parameter
`config`	`GTCaptcha4Config`	Configuration object, optional

The init() method starts preloading. If initialization is performed in the onCreate or onCreateView method, the verification process will be preloaded, enabling faster verification. If init() is called at the time of verification, the loading speed will be slower than preloading. It is recommended to initialize in the onCreate or onCreateView method.

Start Verification

Start the verification process.

Method Description

public void verifyWithCaptcha();

              
              public void verifyWithCaptcha();

このコードブロックはフローティングウィンドウ内に表示されます

Cancel Verification

Cancel the verification process and close the verification window.

Method Description

public void cancel();

              
              public void cancel();

このコードブロックはフローティングウィンドウ内に表示されます

Enable/Disable Log Monitoring

Set to enable or disable log monitoring.

Method Description

public void setLogEnable(boolean enable);

              
              public void setLogEnable(boolean enable);

このコードブロックはフローティングウィンドウ内に表示されます

Obtain Verification Callback

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener); public GTCaptcha4Client addOnFailureListener(OnFailureListener listener); public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

              
              public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

このコードブロックはフローティングウィンドウ内に表示されます

Code Example

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Enable secondary verification }else { // TODO User answer verification failed } } }).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() { @Override public void onWebViewShow() { } })

              
              gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
            // TODO Enable secondary verification
        }else {
            // TODO User answer verification failed
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
      @Override
      public void onWebViewShow() {
      }
  })

このコードブロックはフローティングウィンドウ内に表示されます

Destroy Resources

Destroy resources in the onDestroy lifecycle

public void onDestroy(){ super.onDestroy(); if(gtCaptcha4Client != null){ gtCaptcha4Client.destroy(); } }

              
              public void onDestroy(){
    super.onDestroy();
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

Screen Orientation Change

@Override public void onConfigurationChanged(Configuration newConfig) { super.onConfigurationChanged(newConfig); if(gtCaptcha4Client != null){ gtCaptcha4Client.configurationChanged(newConfig); } }

              
              @Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

このコードブロックはフローティングウィンドウ内に表示されます

Preload Code Example

@Override public void onViewCreated(View view, Bundle savedInstanceState){ super.onViewCreated(view, savedInstanceState); String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // Set service address .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO Disable in production .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 Enable secondary verification }else { // TODO User answer verification failed } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              @Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // Set service address
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO Disable in production
            .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 Enable secondary verification
                    }else {
                        // TODO User answer verification failed
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

このコードブロックはフローティングウィンドウ内に表示されます

Normal Loading Code Example

private void click(){ String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // Set service address .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO Disable in production .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 Enable secondary verification }else { // TODO User answer verification failed } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              private void click(){
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // Set service address
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO Disable in production
            .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 Enable secondary verification
                    }else {
                        // TODO User answer verification failed
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

このコードブロックはフローティングウィンドウ内に表示されます

For detailed code examples, refer to the official Demo

Parameter Configuration

Configure parameters through the GTCaptcha4Config.Builder class

Definition	Description
`setResourcePath`	Must be set to: https://captcha-stat.engagelab.com/www/gt4-index.html
`setApiServers`	Must be set to: captcha-api.engagelab.com
`setStaticServers`	Must be set to: captcha-stat.engagelab.com/www/js
`setParams`	Additional parameters passed to the front-end `js` for use
`setDebug`	Whether to enable `debug` mode, default is `false`, set to `false` in production
`setLanguage`	Specify language, defaults to the app language
`setCanceledOnTouchOutside`	Whether to dismiss on outside touch, default is `true`
`setTimeOut`	Set timeout in `ms`, default is 10000
`setBackgroundColor`	Set background color, default is transparent
`setDialogStyle`	Set dialog theme style, default is `gt4_captcha_dialog_style`
`setDialogShowListener`	Set the listener callback for when the verification window is displayed
`build`	Build the `GTCaptcha4Config` object

Parameters can be configured via the setParams interface as per the API documentation

The setParams interface only accepts basic data types, strings, and JSONArray type data

Handling Errors

Unexpected errors may occur during verification. You can handle them by implementing the addOnFailureListener interface and processing them in the following callback method:

Note: Error callbacks include user-initiated verification cancellations, which can be filtered out separately.

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error){ // Example of returned error content // {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}} // You can parse the error as JSON, replace the error description, and retain the error code Toast.makeText(context, "Verification Error: $error", Toast.LENGTH_SHORT).show() }

              
              gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error){
        // Example of returned error content
        // {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}}
        // You can parse the error as JSON, replace the error description, and retain the error code
        Toast.makeText(context, "Verification Error: $error", Toast.LENGTH_SHORT).show()
    }

このコードブロックはフローティングウィンドウ内に表示されます

It is strongly recommended to display the error code along with the error reason to the user for easier troubleshooting of online issues.

Refer to the following list for possible error codes: Error Code List ```

Android CAPTCHA Integration Guide

Product Introduction

Environment Requirements

Integrating the SDK

Importing the SDK

Configuration for Non-Kotlin Projects

Adding Permissions

Proguard Rules

Interface Configuration

Call Logic

Initialization

Start Verification

Cancel Verification

Enable/Disable Log Monitoring

Obtain Verification Callback

Destroy Resources

Screen Orientation Change

Preload Code Example

Normal Loading Code Example

Parameter Configuration

Handling Errors

Integrating the `SDK`

Importing the `SDK`

Configuration for Non-`Kotlin` Projects

`Adding Permissions`