> >

Web

Configuration parameters

The configuration parameter here refers to the config object (key-value structure) passed in during initialization verification, that is, the optional parameter configuration of the first parameter passed in when calling the initialization function initGeetest4. Please refer to the deployment document for necessary parameters, and refer to 4.0 adaptive captcha demo for demo

With the exception of captchaId, all are optional configuration parameters (the following configuration parameters should not be set unless you know how to use them (which may cause side effects in different scenarios)):

Parameters Required Type Description Default Value Optional Value
captchaId Y string Verify ID, apply it on the dashboard
product N string Set the presentation of the next verification float float、popup、bind
nativeButton N string The style of verify button {width:’260px’,height:’50px’} The units can be px, %, em, rem, pt
rem N number Set the overall scaling ratio of the captcha 1 Different proportional values can be passed in according to different devices
language N string Set the language for the text of verification interface. If it failed to use the browser language or the language isn’t supported in your version, English would be set as default. eng zho, eng, zho-tw, zho-hk, udm, jpn, ind, kor、rus, ara, spa, pon, por, fra, deu
protocol N string Protocol head Default to the protocol head of the current page (For local or mixed development, be sure to set this up manually, otherwise the file protocol will be automatically obtained) http://、https://、file://
timeout N number Set the timeout period for a single request during verification 30000（ms） Integers greater than 0
hideBar N array Hide the “close” button and “refresh” button [] [‘close’,’refresh’]
mask N object The pop-up configuration. Including background color, close the challenge by clicking outside of pop up. {outside:true,bgColor:’#0000004d’} outside:false,bgColor: any css color
apiServers N array Control the address requested by the api [‘gcaptcha4.geetest.com’]
nextWidth N string Width of the captcha pop-up window (after this parameter is set, the captcha pop-up window will not be automatically adjusted according to the web page content width)
riskType N string Combined with risk control integration, specify the verification form
offlineCb N function Process function with downtime mode; GeeTest downtime is the default; setting this function means you want to customize the downtime logic (no longer execute the default downtime mode)
onError N function Error capture before initializing captcha
hideSuccess N boolean Whether to hide the success pop-up window in bind mode. (note: it is only valid when the product parameter value is bind) false true
userInfo N string The information of client, such as acount, phone number, user name, etc.

product

In GeeTest Adaptive CAPTCHA intelligent mode, most real users can pass the verification with just one click, but the request identified as risky will proceed to the next stage of verification, where an interactive pop-up secondary verification will be displayed, which is compatible with the user’s own interface.

Currently, there are three types:

  • float
  • bind
  • popup

For popup and bind types, you can set the following parameters:

Parameters Type Function Description
bgColor string Set the color of the pop-up background The default is black, and any legal color value can be set

The following section presents examples for each style.

Popup:

initGeetest4(
  {
    // Omit required configuration parameters

    product: "popup",
  },
  function (captchaObj) {
    captchaObj.appendTo("#captchaBox"); //Insert the verification button into the captchaBox element in the host page

    captchaObj
      .onReady(function () {
        //your code
      })
      .onSuccess(function () {
        //your code
      })
      .onError(function () {
        //your code
      });
  }
);

float:

initGeetest4(
  {
    // Omit required configuration parameters

    product: "float",
  },
  function (captchaObj) {
    captchaObj.appendTo("#captchaBox"); // Insert the validation button into the captchaBox element in the host page

    captchaObj
      .onReady(function () {
        //your code
      })
      .onSuccess(function () {
        //your code
      })
      .onError(function () {
        //your code
      });
  }
);

bind:

When you choose “bind”, “appendTo” would be replaced by “showCAPTCHA” when it comes to call CAPTCHA verification.

initGeetest4(
  {
    // Omit required configuration parameters

    product: "bind",
  },
  function (captchaObj) {
    captchaObj
      .onReady(function () {
        // please call the showCaptcha method to show the CAPTCHA when it is ready
      })
      .onSuccess(function () {
        // your code, please reset the CAPTCHA based on you business
      })
      .onError(function () {
        //your code
      });

    //press the button to submit event

    button.click = function () {
      // some code

      // check if the CAPTCHA is ready, and if onReady is executed

      captchaObj.showCaptcha(); //show the CAPTCHA

      // some code
    };
  }
);

nativeButton

Adjust the width of the verify button to fit the size of the host page.

Default: 260px * 50px.

Adjust the button as wide as the input box by setting width height:

Example: Set the button width and height to 100% so that the width of the button is the same as that of its parent element.

initGeetest4({
    // Omit required configuration parameters
    nativeButton:{
      height: '100%'
      width: '100%'
    }
    
}, handler);

language

Set the language for captcha interface, there are available languages below. If you request more languages, please contact your account manager.

  • zho（Chinese (Simplified)）
  • eng（English）
  • zho-tw（Chinese (Taiwan)）
  • zho-hk（Chinese (Hong Kong)）
  • udm（Uyghur）
  • jpn（Japanese）
  • ind（Indonesian）
  • kor（Korean）
  • rus（Russian）
  • ara（Arabic）
  • spa（Spanish）
  • pon（Portuguese (Brazil)）
  • por（Portuguese (Europe)）
  • fra（French）
  • deu（German）

Note: The language setting does not change the text on the CAPTCHA image because it is a picture. If you need to set up customized images, you can upload image albums in GeeTest dashboard.

Examples of CAPTCHA images in Chinese and English are shown below:

web-en-1

English：

web-en-2

The sample of set the interface language as English

initGeetest4({
  // Omit required configuration parameters
  language: "eng",
});

protocol

Set the verification request header. Common ones are http:// and https://. The default value is the same as the protocol of the host page.

initGeetest4({
  // Omit required configuration parameters
  protocol: "https://",
});

outside

Set whether to close the captcha by clicking outside of the verification pop-up area, and the default is true.

If you do not want to close the captcha by clicking outside of the verification area, set it to false

initGeetest4({
  // Omit required configuration parameters
  outside: false,
});

timeout

Set the request timeout for each captcha, and the default is 30,000 milliseconds

initGeetest4({
  // Omit required configuration parameters
  timeout: 10000,
});

UserInfo

The information of client, such as acount, phone number, user name, etc.

initGeetest4({
  // Omit required configuration parameters
  userInfo: "user@geetest.com"
});

Initialization

After initializing captcha with initGeetest4, its second parameter is a callback, and the first parameter of the callback is the captcha instance, as shown in the following code.

initGeetest4({
  // TODO  }, function (captchaObj) {
  //You can now call captchaObj instance method
});

Web APIs

appendTo(position)

The appendTo method is used to insert captcha button into the host page so that it displays on the page. The accepted parameter can be either an id selector (for example, # captcha-box) or a DOM element object.

You can input by the following ways:

  1. id selector
<div id="captcha-box"></div>

...

<script>
    initGeetest4(
        // TODO
    }, function (captchaObj) {
        captchaObj.appendTo('#captcha-box');
        // Omit calls to other methods
     });
</script>
  1. DOM element
<div id="captcha-box"></div>
...
<script>
    var captchaBox = document.getElementById('#captcha-box');
    initGeetest4({
        // TODO
    }, function (captchaObj) {
        captchaObj.appendTo(captchaBox);
        //Omit calls to other methods
    });
</script>

getValidate()

Get the verification result from onSuccess if the end user has successfully answered the captcha question. This result is used to perform secondary verification in server SDK. The getValidate method returns an object that contains some of the fields required for verification.

If the verification fails, false will be returned. The developer can decide whether to proceed to the next step (submit the form or ajax for secondary verification) based on the return value.

Perform secondary verification with ajax

initGeetest4(
  {
    // TODO
  },
  function (captchaObj) {
    // Omit calls to other methods
    // The onSuccess method is called, which is described below

    captchaObj.onSuccess(function () {
      var result = captchaObj.getValidate();

      //ajax pseudocode
      $.ajax({
        url: "server",
        data: result,
        dataType: "json",
        success: function (res) {
          console.log(res.result);
        },
      });
    });
  }
);

reset()

Reset captcha. It is used when the user’s background detects that the captcha is successful yet other information is incorrect (such as the username and password are incorrect), or the error occurs with the captcha. Therefore, it can only be used in case of success or error. For bind type, calling showCaptcha again after success will automatically reset captcha without active call

The following is an example that reset the captcha when an account or password is incorrect.

initGeetest4({
     // TODO
}, function (captchaObj) {
     // Omit calls to other methods
     // The onSuccess method is called, which is described below
     captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();
        // ajax pseudocode
        lot_number: result.lot_number,
        captcha_output: result.captcha_output,
        pass_token: result.pass_token,
        gen_time: result.gen_time,
        username: 'xxx',
        password: 'xxx'
        // Other data required by the server, such as the login username and password
    }, function (data) {
        //Carry out operations such as jumping based on the result of secondary verification at the server
        if (data.status === 'fail') {
             alert('Incorrect username or password, please re-enter and complete verification');
             captchaObj.reset();  // Call this interface to reset
        }

    });
});

showCaptcha()

When the product is of type bind, you can call this interface for verification.

The advantage of this form is that it allows developers to check the data filled in by users and then call the verification interface if no problems are found.

Pay attention to the timing of the call. There will be no response when calling this method before the captcha is in onReady state.

<div id="btn">Submit button</div>

<script>
initGeetest4({
     // TODO
    product: 'bind'
}, function (captchaObj) {
     //Omit calls to other methods
    document.getElementById('btn').addEventListener('click', function () {
        if (check()) { // Check whether submission can proceed or not
             captchaObj.showCaptcha();
        }
    });

    captchaObj.onSuccess(function () {
         //After successful user verification, perform the actual submission
        // todo
    })
});
</script>

onReady(callback)

Detect if the DOM element which contains the captcha button is ready. The parameter callback is a function type.

Hide the Load Verification Prompt according to the onReady event

<div id="captcha-box">
    <div id="loading-tip">Loading, please wait....</div>
</div>

<script>
    initGeetest4({
        // TODO
    }, function (captchaObj) {
        captchaObj.appendto('#captcha-box');
        // Omit calls to other methods
        captchaObj.onReady(function () {
            // Hide the # loading-tip element when the DOM is ready
            // The following is the sample code. You can hide #loading-tip by the way that you prefer
            document.getElementById('loading-tip').style.display = 'none';
        });
    });
</script>

onNextReady(callback)

Detect if the load event that verifies the next resource is ready. The parameter callback is a function type.

<div id="captcha-box">
    <div id="loading-tip">Loading, please wait...</div>
</div>

<script>
    initGeetest4({
        // TODO
    }, function (captchaObj) {
        captchaObj.appendto('#captcha-box');
        // Omit calls to other methods
        captchaObj.onNextReady(function () {
        });
    });
</script>

onSuccess(callback)

Detect for the verification success event. The parameter callback is a function type.

Detect for the verification success event to perform the secondary verification.

initGeetest4({
    // TODO
}, function (captchaObj) {
    // Omit calls to other methods
    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajaxpseudocode, secondary verification
        ajax('/login', {
            lot_number: result.lot_number,
            captcha_output: result.captcha_output,
            pass_token: result.pass_token,
            gen_time: result.gen_time,
            // Other data required by the server, such as the login username and password
        }, function (data) {
            // Carry out operations such as jumping based on the result of secondary verification at the server
        });
    });
});

onFail(callback)

Detect for the verification success event. The parameter callback is a function type.

FailObj failure objects include: captcha_id, captcha_type, challenge, which may be added later.

Detect for the failure events of captcha operations and count the failures of user operation

initGeetest4({
    // TODO
}, function (captchaObj) {
    // Omit calls to other methods
    captchaObj.onFail(function (failObj) {
        // Count error messages
    });
});

onError(callback)

Detect the verification error event. The parameter callback is a function type.

The onError callback will be triggered whenever there are errors (refer to ErrorCode) that can be caught by captcha, such as excessive refresh, failed loading of static resources, and poor network.

The error object consists of three parts: code: error code, msg: prompt information, and desc: This object contains the detail attribute, which describes the specific error information, and may be added later

When an error event is triggered, the user can be prompted to refresh the page and try again.

initGeetest4({
     // TODO
}, function (captchaObj) {
    // Omit calls to other methods
    captchaObj.onError(function (error) {
        // There is an error. You can remind the user to try again later.
        // error contains error_code、msg
        // {code: '60000',msg:"User Configuration Error"，desc:{ detail:  "User id is Missing"}}
    });
});

onClose(callback)

This callback is triggered when the user turns off the pop-up verification.

initGeetest4({
    // TODO
    product: 'bind'
}, function (captchaObj) {
    // Omit calls to other methods
    captchaObj.onClose(function () {
        // User closes the captcha. You can prompt the user to complete the verification to proceed to the next step.
    });
});

destroy

Destroy the captcha instance, captcha associated UI, and the event listeners registered with the captcha will be removed.

initGeetest4({
     // TODO
    product: 'bind'
}, function (captchaObj) {
    // Omit calls to other methods
    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajaxPseudocode
        ajax('/login', {
            lot_number: result.lot_number,
            captcha_output: result.captcha_output,
            pass_token: result.pass_token,
            gen_time: result.gen_time,
            username: 'xxx',
            password: 'xxx'
            // Other data required by the server, such as the login username and password
        }, function (data) {
            // Carry out operations such as jumping based on the result of secondary verification at the server
            if (data.status === 'fail') {
                alert('Incorrect username or password, please re-enter and complete verification');
                captchaObj.reset();//Call this interface to reset
            } else if(data.status === 'success') {
                // Determine whether validation needs to be removed in combination with business logic
                captchaObj.destroy();
                captchaObj = null;
            }
        });
    });
});
Was this helpful?
Send