> >

Android

Overview and resources

GeeTest Adaptive CAPTCHA Android SDK is available to developers who integrate Android native client development.

Environmental requirements

Item Resources
Development object Android 5.0+
Developing environment Android Studio 4.1
Compilation tools Gradle (extract jar and resource files for ant compilation)
System dependent None
Third-party dependency of SDK None
Bundle increment 60K
Item Resource address
Product structure process Communication process, interaction process
Error Code List Error Code List
SDK resource bundle Download from GeeTest dashboard

Installation

Integrate SDK

Download .zip file from SDK resource bundle link to get the latest sdk.

Import SDK

Drag and drop .aar file from the zip package to the libs folder in the project. After that, check whether .aar has been added to Library, and add the following code under the build.gradle of the project:

repositories {
        flatDir {
            dirs 'libs'
        }
    }

Add dependencies to the aar package manually (AAR does not pass third-party dependencies by default, so you need to add them manually):

implementation(name: 'geetest_captcha_android_vx.y.z_date', ext: 'aar')

Non-Kotlin project configuration

build.gradle configuration in root directory

ext.kotlin_version = "1.4.10"

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

build.gradle configuration in introducing module

apply plugin: 'kotlin-android'

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

Note: If there is a conflict between kotlin versions, exclude kotlin dependencies (group: ‘org.jetbrains.kotlin’)

Add permission

<!--Required--Default Request-->
<uses-permission android:name="android.permission.INTERNET" />

<!--Required when the minSdkVersion is below 23--Default Not Request--> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--Optional - 6.0 or above requires dynamic application (store log for easy analysis and error reporting, log path/sdcard/Geetest/captcha_log.txt）-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Obfuscation rules

GeeTest SDK has already been obfuscated. Obfuscating one more time may lead to unexpected error. By default the aar package already contains a proguard consumer rules file which can prevent duplicate obfuscating, therefore there should be no additional operation required. If you need to extract aar to separate jar and resource files, please copy the content of proguard.txt to your application’s proguard rule.

If a resource obfuscation tool is used, add it to the whitelist for configuration:

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

Configure interface

Logic flow

  1. Configure initialization
  2. Start verification
  3. Get validation callback
  4. Destroy resources

As shown in the product workflow process, you need to set up Server interface in your backend first,
and configure it with captchaId and Key
you got from GeeTest dashbaord.

Initialization

SDK initialization configuration information can be initialized by onCreate or onCreateView method

Method:

public static GTCaptcha4Client getClient(Context context);

public GTCaptcha4Client init(String captchaId);

public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

Parameter description:

Parameters Type Description
context Context The context object must be an Activity instance
appId String APP_ID, required parameters
config GTCaptcha4Config Parameter configuration object, not required

init () method initializes pre-loading, and if initialized in onCreate or onCreateView methods, the verification process is loaded ahead of time to evoke verification more quickly. If init () when you need to invoke verification, the loading speed is slower than pre-loading, so it is recommended to initialize it in onCreate or onCreateView methods.

Start verification

Start verification process

Method:

public void verifyWithCaptcha();

Cancel the verification and close window

Method:

public void cancel();

Turn log monitoring on/off

Method:

public void setLogEnable(boolean enable);

Get verification callback

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);

public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);

public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

Sample code

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {

    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
             // TODO start on secondary verification
        }else {
             // TODO user answer verification error
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
        @Override
        public void onWebViewShow() {
        }
    })

Release resources

Release resources in onDestroy()

public void onDestroy(){
    super.onDestroy();

    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}

Landscape and portrait mode switching

@Override

public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);

    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

Sample code of Preloading method

@Override

public void onViewCreated(View view, Bundle savedInstanceState){

    super.onViewCreated(view, savedInstanceState);

    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setDebug(true) // TODO release version must be closed
            .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 start on secondary verification
                    } else {
                      // TODO user answer verification error
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

Normal loading code sample

private void click(){

    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setDebug(true) // TODO release version must be closed
            .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 start on secondary verification
                    } else {
                      // TODO user answer verification error
                    }
                }

            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {

                @Override
                public void onFailure(String error) {
                }

            })
            .verifyWithCaptcha();
}

Refer to the official Demo for sample code details

Parameter configuration

Configure parameters through GTCaptcha4Config.Builder

Definition Description
setParams Additional parameters will be passed to the front-end js for use
setDebug Whether to debug mode, default is false, please set it to false online
setLanguage Specify the language, following the application language by default
setCanceledOnTouchOutside Click on, whether the area outside will disappear, and the default is true
setTimeOut Set timeout, unit ms, 10000 by default
setResourcePath Set the intermediate address and load the local html file by default
setBackgroundColor Set the background color, which is transparent by default
setDialogStyle Set the theme style for captcha dialog, gt4_captcha_dialog_style by default
setDialogShowListener Set the listening callback displayed in the verification window
build Build the GTCaptcha4Config object

Please check API ref docs for more information about setParams

Note: The setParams interface can only accept data of basic data types, strings, and JSONArray types

Handle verification errors

Some unexpected errors may occur, You can process in the following callback method after implementing the ‘addOnFailureListener’ interface:

Note: The error callback includes the user’s active cancellation of authentication, which can be filtered out separately.

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error){
        // Return error content example
        // {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
        // The error can be parsed by json, the error description can be replaced by itself, and the error code can be reserved
        Toast.makeText(context, "Validation error: $error", Toast.LENGTH_SHORT).show()
    }

It is strongly recommended to present both an error message and error code to the end user. This will facilitate subsequent troubleshooting.

Please refer to the following list for possible error codes: Error Code List

Was this helpful?
Send