Android SDK API

External Support Utility Class

Method

getClient(Context)

Retrieve the GTCaptcha4Client utility class object

Declaration

              
              public static GTCaptcha4Client getClient(Context context)

            

Parameters

Discussion

Note: This is not a singleton implementation. The GTCaptcha4Client object obtained through getClient() needs to be saved for use in onDestroy or other lifecycle methods.

init(String)

Initialize with default configuration

Declaration

              
              public GTCaptcha4Client init(String captchaId)

            

Parameters

Discussion

Note: Calling the init() method immediately starts the captcha loading process. If it is called before the onResume() lifecycle, the captcha will be preloaded. When verifyWithCaptcha() is executed to display the captcha, it will load and display quickly. The same applies below.

init(String, GTCaptcha4Config)

Initialize with custom configuration

Declaration

              
              public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

            

Parameters

addOnSuccessListener(GTCaptcha4Client.OnSuccessListener)

Add a listener for verification results, which is called back when the captcha is successfully loaded and the user solves the captcha.

Declaration

              
              public GTCaptcha4Client addOnSuccessListener(GTCaptcha4Client.OnSuccessListener response)

            

Parameters

addOnFailureListener(GTCaptcha4Client.OnFailureListener)

Add a listener for captcha loading failure, which is triggered when an error occurs during the captcha loading process.

Declaration

              
              public GTCaptcha4Client addOnFailureListener(GTCaptcha4Client.OnFailureListener listener)

            

Parameters

addOnWebViewShowListener(GTCaptcha4Client.OnWebViewShowListener)

Add a listener for successful frontend verification loading. When the frontend verification is successfully loaded, the callback is triggered. If preloading is completed, the callback is triggered immediately after calling verifyWithCaptcha.

Declaration

              
              public GTCaptcha4Client addOnWebViewShowListener(GTCaptcha4Client.OnWebViewShowListener listener)

            

Parameters

verifyWithCaptcha()

Start the verification process and load the captcha.

Declaration

              
              public GTCaptcha4Client verifyWithCaptcha()

            

Discussion

Note: Before calling verifyWithCaptcha(), you need to call init(), addOnSuccessListener(), and addOnFailureListener(); otherwise, errors may occur.

cancel()

Cancel the verification and close the verification window.

Declaration

              
              public void cancel()

            

Discussion

Note: Before calling cancel(), you need to call init(), addOnSuccessListener(), and addOnFailureListener(); otherwise, errors may occur.

setLogEnable(boolean enable)

Enable or disable log monitoring.

Declaration

              
              public void setLogEnable(boolean enable)

            

Discussion

Calling setLogEnable controls the log printing functionality.

destroy()

Destroy resources with a long lifecycle.

Declaration

              
              public void destroy()

            

Discussion

Destroy verification resources. This method must be called.

Discussion

This method should be called during the onDestroy lifecycle of the captcha interface used by the client.

configurationChanged(Configuration)

Handle screen orientation changes.

Declaration

              
              public void configurationChanged(Configuration newConfig)

            

Discussion

This method should be called during the onConfigurationChanged lifecycle method for screen orientation changes.

getVersion()

Retrieve the version number.

Declaration

              
              public static String getVersion()

            

Return Value

Returns the version number as a String.

isSupportWebView(Context)

Check whether the system supports WebView. If not supported, it is recommended to use a fallback logic.

Declaration

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

            

Return Value

Description of the Pair object:

GTCaptcha4Config#Builder

Parameter configuration class.

setTimeOut(int)

Set the request timeout duration.

Declaration

              
              public Builder setTimeOut(int timeOut)

            

Parameters

setResourcePath(String)

Set the resource path for WebView loading.

Declaration

              
              public Builder setResourcePath(String html)

            

Parameters

Discussion

By default, it loads the gt4-index*.html file in the assets directory. This interface does not need to be set unless there are special requirements.

setLanguage(String)

Set the language for JS transmission. This interface can only control the language of the loaded WebView, while the SDK's language follows the current application.

Declaration

              
              public Builder setLanguage(String language)

            

Parameters

Discussion

If set to null or not set, the default language short code of the application will be transmitted to the frontend.

setCanceledOnTouchOutside(boolean)

Set whether clicking the gray area will dismiss the dialog. The default is to dismiss.

Declaration

              
              public Builder setCanceledOnTouchOutside(boolean canceledOnTouchOutside)

            

Parameters

setDebug(boolean)

Set whether it is in debug mode. For production, it must be set to false or not configured.

Declaration

              
              public Builder setDebug(boolean debug)

            

Parameters

setBackgroundColor(int)

Sets the background color of WebView, which controls the background color of the Android WebView component and is different from the background color of the front-end JS.

Declaration

              
              public Builder setBackgroundColor(int backgroundColor)

            

Parameters

setDialogStyle(String)

Sets the theme style of the verification dialog box.

Declaration

              
              public Builder setDialogStyle(String dialogStyle)

            

Parameters

Declaration

The following is the default theme style:

              
              <style name="gt4_captcha_dialog_style" parent="android:Theme.Dialog">
    <!-- No window frame for the Dialog -->
    <item name="android:windowFrame">@null</item>
    <!-- Whether it floats above the activity -->
    <item name="android:windowIsFloating">true</item>
    <!-- Whether it is translucent -->
    <item name="android:windowIsTranslucent">true</item>
    <!-- Removes the title -->
    <item name="android:windowNoTitle">true</item>
    <item name="android:windowContentOverlay">@null</item>
    <!-- Whether to use a black translucent background outside the display area -->
    <item name="android:backgroundDimEnabled">true</item>
    <!-- Sets the background of the dialog -->
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:padding">0dp</item>
</style>

            

setDialogShowListener(GTCaptcha4Client.OnDialogShowListener)

Sets the listener callback for when the verification window is displayed.

Declaration

              
              public void setDialogShowListener(GTCaptcha4Client.OnDialogShowListener dialogShowListener)

            

Parameters

setParams(Map<String, Object>)

Configures additional parameters, which are fully passed to JS.

Declaration

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

            

Parameters

Discussion

Supported key-value pairs are as follows:

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);

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

            

build()

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

Declaration

              
              public GTCaptcha4Config build()

            

GTCaptcha4Client#OnSuccessListener

Callback listener for verification results.

onSuccess(Boolean, String)

Verification interface callback.

Declaration

              
              void onSuccess(Boolean status, String response)

            

Parameters

Param |Type | Description ------ |-----|----- status |Boolean | Result of user operation verification, true for success, false for failure. Failure will refresh the verification style. response | String | When user operation verification succeeds, the response data needs to be sent to the server for verification.

Discussion

Description of successful verification:

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

            

Description of failed verification:

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

            

GTCaptcha4Client#OnFailureListener

Callback listener for loading failure.

onFailure(String)

Loading failure callback.

Declaration

              
              void onFailure(String error)

            

Parameters

Param |Type | Description ------ |-----|----- error | String | Description of verification loading failure. Note: Includes user-initiated cancellation.

Discussion

Description of loading failure:

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

            

GTCaptcha4Client#OnWebViewShowListener

Callback listener for successful front-end verification loading.

onWebViewShow()

Front-end verification loading success.

Declaration

              
              void onWebViewShow()

            

Discussion

Callback after front-end verification loading is successful. If preloading is completed, this callback is triggered immediately after calling verifyWithCaptcha.

GTCaptcha4Client#OnDialogShowListener

Callback listener for the display of the verification window.

actionBeforeDialogShow(Dialog)

Callback before the verification window is displayed.

Declaration

              
              void actionBeforeDialogShow(Dialog dialog)

            

Parameters

Param |Type | Description ------ |-----|----- dialog | Dialog | Instance of the verification window.

actionAfterDialogShow()

Callback after the verification window is displayed.

Declaration

              
              void actionAfterDialogShow(Dialog dialog)

            

Parameters

Param |Type | Description ------ |-----|----- dialog | Dialog | Instance of the verification window.

Discussion

You can change system styles here, such as hiding the navigation bar, hiding the status bar, etc.

onDialogFocusChanged()

Callback when the focus of the verification window changes.

Declaration

              
              void onDialogFocusChanged(Dialog dialog, boolean hasFocus)

            

Parameters

Param |Type | Description ------ |-----|----- dialog |Dialog | Instance of the verification window. hasFocus | boolean | Whether it has focus.