GeelabCaptchaClient

The primary public client class for Geelab Captcha 4.0.

Methods

getClient(Context)

Returns a GeelabCaptchaClient instance.

Declaration

public static GeelabCaptchaClient getClient(Context context)

Parameters

Discussion

This is not a singleton implementation. Retain the GeelabCaptchaClient instance returned by getClient() so that it is available from onDestroy and other lifecycle callbacks.

init(String)

Initializes the client with the default configuration.

Declaration

public GeelabCaptchaClient init(String captchaId)

Parameters

Discussion

Calling init() starts loading the captcha. Calling it before onResume() preloads the captcha so that it can be displayed quickly when verifyWithCaptcha() is called. The same applies below.

init(String, GeelabCaptchaConfig)

Initializes the client with a custom configuration.

Declaration

public GeelabCaptchaClient init(String captchaId, GeelabCaptchaConfig config)

Parameters

addOnSuccessListener(GeelabCaptchaClient.OnSuccessListener)

Registers a listener for captcha results. The listener is called after the captcha is loaded and the user completes an answer.

Declaration

public GeelabCaptchaClient addOnSuccessListener(GeelabCaptchaClient.OnSuccessListener response)

Parameters

addOnFailureListener(GeelabCaptchaClient.OnFailureListener)

Registers a listener for captcha loading failures.

Declaration

public GeelabCaptchaClient addOnFailureListener(GeelabCaptchaClient.OnFailureListener listener)

Parameters

addOnWebViewShowListener(GeelabCaptchaClient.OnWebViewShowListener)

Registers a listener that is called when the verification frontend has loaded. When preloading is complete, the listener is called immediately after verifyWithCaptcha().

Declaration

public GeelabCaptchaClient addOnWebViewShowListener(GeelabCaptchaClient.OnWebViewShowListener listener)

Parameters

verifyWithCaptcha()

Starts the verification flow and displays the captcha.

Declaration

public GeelabCaptchaClient verifyWithCaptcha()

Discussion

Call init(), addOnSuccessListener(), and addOnFailureListener() before calling verifyWithCaptcha(), otherwise an error may occur.

cancel()

Cancels verification and closes the verification window.

Declaration

public void cancel()

Discussion

Call init(), addOnSuccessListener(), and addOnFailureListener() before calling cancel(), otherwise an error may occur.

setLogEnable(boolean)

Enables or disables diagnostic logs.

Declaration

public void setLogEnable(boolean enable)

Discussion

setLogEnable controls SDK log output.

destroy()

Releases resources with a long lifecycle.

Declaration

public void destroy()

Discussion

Releases verification resources. You must call this method in the onDestroy lifecycle callback of the screen that uses the captcha.

configurationChanged(Configuration)

Handles orientation changes.

Declaration

public void configurationChanged(Configuration newConfig)

Discussion

Call this method from the onConfigurationChanged lifecycle callback when the device orientation changes.

getVersion()

Returns the SDK version.

Declaration

public static String getVersion()

Return Value

The version number as a String.

isSupportWebView(Context)

Checks whether the system WebView is supported. If it is not supported, use a fallback flow.

Declaration

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

Return Value

GeelabCaptchaConfig#Builder

The configuration builder.

setTimeOut(int)

Sets the request timeout.

Declaration

public Builder setTimeOut(int timeOut)

Parameters

setResourcePath(String)

Sets the resource URL loaded by WebView.

Declaration

public Builder setResourcePath(String html)

Parameters

Discussion

By default, the SDK loads gl4-index*.html from the assets directory. Do not set this option unless custom resources are required.

setLanguage(String)

Sets the language sent to the JavaScript frontend. This setting controls only the language of the loaded WebView; the SDK UI follows the current application language.

Declaration

public Builder setLanguage(String language)

Parameters

Discussion

When this value is null or not set, the application default language code is sent to the frontend.

setCanceledOnTouchOutside(boolean)

Sets whether the dialog is dismissed when the dimmed area is tapped. The default is true.

Declaration

public Builder setCanceledOnTouchOutside(boolean canceledOnTouchOutside)

Parameters

setDebug(boolean)

Enables or disables debug mode. Set this to false, or leave it unset, in production.

Declaration

public Builder setDebug(boolean debug)

Parameters

setBackgroundColor(int)

Sets the Android WebView control background color. This is distinct from the JavaScript frontend background color.

Declaration

public Builder setBackgroundColor(int backgroundColor)

Parameters

setDialogStyle(String)

Sets the captcha dialog theme.

Declaration

public Builder setDialogStyle(String dialogStyle)

Parameters

The following is the default theme style:

<style name="geelab_captcha_dialog_style" parent="android:Theme.Dialog">
    <!-- Remove the Dialog window frame -->
    <item name="android:windowFrame">@null</item>
    <!-- Display above the activity -->
    <item name="android:windowIsFloating">true</item>
    <!-- Make the window translucent -->
    <item name="android:windowIsTranslucent">true</item>
    <!-- Remove the title -->
    <item name="android:windowNoTitle">true</item>
    <item name="android:windowContentOverlay">@null</item>
    <!-- Use a dimmed background outside the displayed area -->
    <item name="android:backgroundDimEnabled">true</item>
    <!-- Set the dialog background -->
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:padding">0dp</item>
</style>

setDialogShowListener(GeelabCaptchaClient.OnDialogShowListener)

Sets the listener for verification-window display events.

Declaration

public void setDialogShowListener(GeelabCaptchaClient.OnDialogShowListener dialogShowListener)

Parameters

setParams(Map<String, Object>)

Sets additional parameters. These parameters are passed directly to JavaScript.

Declaration

public Builder setParams(Map<String, Object> params)

Parameters

Discussion

Supported key-value pairs are listed below.

Sample Code

Map<String, Object> params = new HashMap<>();
params.put("displayMode", 0);
params.put("protocol", "https://");
params.put("bgColor", "#CC0000FF");
params.put("loading", "./loading_test.gif");
params.put("rem", 0.6);
JSONArray hideBar = new JSONArray()
        .put("close")
        .put("refresh");
params.put("hideBar", hideBar);
params.put("nextWidth", "300px");
params.put("hideSuccess", true);

GeelabCaptchaConfig.Builder builder = new GeelabCaptchaConfig.Builder()
        .setParams(params);

build()

Builds a GeelabCaptchaConfig object for use with init().

Declaration

public GeelabCaptchaConfig build()

GeelabCaptchaClient#OnSuccessListener

The verification-result callback listener.

onSuccess(Boolean, String)

Called with the verification result.

Declaration

void onSuccess(Boolean status, String response)

Parameters

Discussion

A successful verification response resembles the following:

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

A failed verification response resembles the following:

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

GeelabCaptchaClient#OnFailureListener

The captcha-loading failure callback listener.

onFailure(String)

Called when captcha loading fails.

Declaration

void onFailure(String error)

Parameters

Discussion

A loading failure response resembles the following:

{"code":"-14460","msg":"Verification session cancelled","desc":{"description":"User cancelled 'Captcha'"}}

GeelabCaptchaClient#OnWebViewShowListener

The verification-frontend loaded callback listener.

onWebViewShow()

Called after the verification frontend is loaded. When preloading is complete, it is called immediately after verifyWithCaptcha().

Declaration

void onWebViewShow()

GeelabCaptchaClient#OnDialogShowListener

The listener for verification-window display events.

actionBeforeDialogShow(Dialog)

Called before the verification window is displayed.

Declaration

void actionBeforeDialogShow(Dialog dialog)

Parameters

actionAfterDialogShow(Dialog)

Called after the verification window is displayed.

Declaration

void actionAfterDialogShow(Dialog dialog)

Parameters

Discussion

Use this callback to adjust system UI, such as hiding the navigation bar or status bar.

onDialogFocusChanged()

Called when the verification window focus changes.

Declaration

void onDialogFocusChanged(Dialog dialog, boolean hasFocus)

Parameters

Error Codes