Android Integration

Requirements

Item	Requirement
Development Target	Android native client
Kotlin Version	1.6.22+
Third-party Dependencies	None (AAR does not transitively include third-party dependencies by default)

The SDK is provided in AAR format, supporting local dependency integration.

Installation

Import AAR File

Drag the .aar file (geelab_captcha_android_vx.y.z_date.aar) from the zip package into the libs folder of your project.

Configure Gradle

Add the following code to your project's build.gradle:

build.gradle

repositories {
    flatDir {
        dirs 'libs'
    }
}

Add Dependency

Manually add the aar package as a dependency:

build.gradle

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

Please replace the filename with the actual downloaded AAR filename.

Non-Kotlin Project Configuration

If your project is not a Kotlin project, you need to add Kotlin support.

Configure in root directory build.gradle:

build.gradle (Project)

ext.kotlin_version = "1.6.22"

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

Configure in module build.gradle:

build.gradle (Module)

apply plugin: 'kotlin-android'

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

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

Permission Configuration

Add necessary permissions in AndroidManifest.xml:

AndroidManifest.xml

<!-- Required - Requested by default -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Must be declared for compatibility with API 23 and below (required for 4.x and 5.x systems) -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

ProGuard Rules

Important: The SDK's AAR package has already been obfuscated. Double obfuscation will cause unpredictable errors.

By default, the AAR package contains the current SDK's ProGuard configuration. Both remote dependencies and local AAR dependencies can ensure the SDK is not obfuscated twice.

If you need to extract the AAR package and integrate JAR and resource files separately, be sure to copy the contents of the proguard.txt file from the extracted directory to your application's ProGuard configuration.

andRes Resource Obfuscation

If you are using andRes for resource obfuscation, please exclude SDK internal resources from obfuscation:

Resource Obfuscation Exclusion

"R.string.geelab_*",
"R.style.geelab_*",

Basic Integration

Initialize in onCreate or onCreateView method to preload the verification process:

Preload Integration

@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);

    // 1. Configure parameters
    GeelabCaptchaConfig config = new GeelabCaptchaConfig.Builder()
            .setDebug(true)  // TODO Must be disabled in production
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();

    // 2. Initialize client
    geelabCaptchaClient = GeelabCaptchaClient.getClient(activity)
            .init("your_captcha_id", config);
}

private void click() {
    // 3. Add callback listeners
    geelabCaptchaClient
            .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if (status) {
                        // TODO Enable secondary verification
                    } else {
                        // TODO User answer verification failed
                    }
                }
            })
            .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                    // TODO Handle verification failure
                }
            })
            .verifyWithCaptcha();
}

Preload method can improve user experience and reduce waiting time.

Initialize when verification needs to be triggered:

Normal Load Integration

private void click() {
    // 1. Configure parameters
    GeelabCaptchaConfig config = new GeelabCaptchaConfig.Builder()
            .setDebug(true)  // TODO Must be disabled in production
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();

    // 2. Initialize and start verification
    geelabCaptchaClient = GeelabCaptchaClient.getClient(activity)
            .init("your_captcha_id", config)
            .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if (status) {
                        // TODO Enable secondary verification
                    } else {
                        // TODO User answer verification failed
                    }
                }
            })
            .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                    // TODO Handle verification failure
                }
            })
            .verifyWithCaptcha();
}

Refer to the official Demo for detailed example code.

Configuration Options

Configuration Parameters

Configure parameters through the GeelabCaptchaConfig.Builder class:

Parameter	Description
`setParams`	Additional parameters that will be passed to the frontend `js`
`setDebug`	Whether to enable `debug` mode, default `false`, must be set to `false` in production
`setLanguage`	Specify language, defaults to application language
`setCanceledOnTouchOutside`	Whether to dismiss when clicking outside, default `true`
`setTimeOut`	Set timeout in `ms`, default 10000
`setResourcePath`	Set intermediate address, defaults to loading local `html` file
`setBackgroundColor`	Set background color, default transparent
`setDialogStyle`	Set dialog theme style, default value `geelab_captcha_dialog_style`
`setDialogShowListener`	Set listener callback for verification window display
`build`	Build `GeelabCaptchaConfig` object

The setParams interface can only accept basic data types, strings, and JSONArray type data.

Initialization Methods

Initialization API

public static GeelabCaptchaClient getClient(Context context);
public GeelabCaptchaClient init(String captchaId);
public GeelabCaptchaClient init(String captchaId, GeelabCaptchaConfig config);

Parameter Description:

Parameter	Type	Description
`context`	`Context`	Context object, must be an `Activity` instance
`captchaId`	`String`	Verification ID, required parameter
`config`	`GeelabCaptchaConfig`	Parameter configuration object, optional

Handling Verification Results

Callback Listeners

Callback Interfaces

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

Complete Example

Handle Verification Results

geelabCaptchaClient
    .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
        @Override
        public void onSuccess(boolean status, String response) {
            if (status) {
                // Verification successful, submit to backend for secondary verification
                submitToBackend(response);
            } else {
                // User answer verification failed
                Toast.makeText(context, "Verification failed, please try again", Toast.LENGTH_SHORT).show();
            }
        }
    })
    .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
        @Override
        public void onFailure(String error) {
            // Verification process error
            Log.e("Captcha", "Verification error: " + error);
        }
    })
    .addOnWebViewShowListener(new GeelabCaptchaClient.OnWebViewShowListener() {
        @Override
        public void onWebViewShow() {
            // Callback when WebView is displayed
            Log.d("Captcha", "Verification window displayed");
        }
    });

Important: You must perform secondary verification on the server side. Do not rely solely on client-side results.

API Methods

Start Verification

Start the verification process:

public void verifyWithCaptcha();

Cancel Verification

Cancel the verification process and close the verification window:

public void cancel();

Lifecycle Management

Destroy Resources

Destroy resources in the onDestroy lifecycle:

Resource Release

@Override
public void onDestroy() {
    super.onDestroy();
    if (geelabCaptchaClient != null) {
        geelabCaptchaClient.destroy();
    }
}

Be sure to call the destroy() method to release resources when the Activity is destroyed.

Screen Orientation Changes

Handle configuration changes:

Screen Orientation Adaptation

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

Log Control

Enable or disable log printing monitoring:

Log Switch

public void setLogEnable(boolean enable);

Error Handling

Some unexpected errors may occur during the verification process. You can handle them by implementing the addOnFailureListener interface:

Error Handling Example

geelabCaptchaClient.addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
    @Override
    public void onFailure(String error) {
        // Example error content returned
        // {"code":"-14460","msg":"Verification session cancelled","desc":{"description":"User cancelled 'Captcha'"}}

        try {
            JSONObject errorObj = new JSONObject(error);
            String code = errorObj.getString("code");
            String msg = errorObj.getString("msg");

            // Display error message and error code to user
            String message = String.format("Verification error [%s]: %s", code, msg);
            Toast.makeText(context, message, Toast.LENGTH_SHORT).show();

            // Log error details
            Log.e("Captcha", "Verification error details: " + error);
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }
});

Strongly recommended to display the error code along with the error message to users, which helps troubleshoot production issues.

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

Common Issues

Next Steps

Check Server Integration to learn about backend verification
Read API Reference for complete API documentation
View FAQ to resolve integration issues

Android Integration

Language setting not taking effect?

How to remove or customize loading?

On this page