>

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 the id, and apply for GeeTest in the background
product N string Set the presentation of the next verification float float、popup、bind
btnWidth N string Set the length of the button 260px The units can be px, %, em, rem, pt
btnHeight N string Set the width of the button 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 the language set by the browser is not transmitted by default, it is not in the supported list, and Chinese is used by default zho 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
outside N boolean Click outside the captcha area to close verification true false
bgColor N string Background color of pop-up window #0000004d Any legal css color unit can be used
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

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:

product

  • 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:

For the bind type, the appendTo interface call will be invalid, and the showBox instance method will be called for verification.

initGeetest4(
{
// Omit required configuration parameters

product: "bind",
},
function (captchaObj) {
captchaObj
.onReady(function () {
//You can't call the showbox method to display the captcha until the captcha is ready
})
.onSuccess(function () {
//your code
})
.onError(function () {
//your code
});

//Button submit event

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

//Check whether the captcha is ready and whether the onReady of the captcha is executed

captchaObj.showBox(); //Display captcha

// some code
};
}
);

btnWidth

Adjust the width of the captcha button to make it fit the host page.

Default: 260px * 50px.

Make the button the same width as the input box by setting btnWidth btnHeight:

Example: Make the button the same width as its parent by setting the width and height of the button to 100%

initGeetest4({
// Omit required configuration parameters
btnHeight: '100%'
btnWidth: '100%'
}, handler);

language

Set the language for captcha interface. Languages available:

  • 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

Set the interface language to English

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

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

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({
// Omit configuration parameters }, function (captchaObj) {
//You can now call captchaObj instance method
});

API Method

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(
// Omit configuration parameters
}, 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({
// Omit configuration parameters
}, 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. Web site developers 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(
{
// Omit configuration parameters
},
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 showBox 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({
// Omit configuration parameters
}, 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
}

});
});

showBox()

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({
// Omit configuration parameters
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.showBox();
}
});

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({
// Omit configuration parameters
}, 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({
// Omit configuration parameters
}, 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({
// Omit configuration parameters
}, 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({
// Omit configuration parameters
}, 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({
// Omit configuration parameters
}, 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({
// Omit configuration parameters
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({
// Omit configuration parameters
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