Configuration
The parameter configuration refers to the config
object (key-value structure) which is passed during the captcha verification. It is the first parameter passed when called the initGeetest
. Please check the client integration documentation for the required parameters. The followings parameters are optional to be configured.
Variables | Type | Description | Default value | Value |
---|---|---|---|---|
product |
String | captcha challenge pop-out style | popup |
float , popup , custom , bind |
width |
String | Width of the captcha button | 300px |
The width could be in px ,% ,em ,rem ,pt . |
lang |
String | Language of captcha | zh-cn |
zh-cn 、zh-hk 、zh-tw 、en 、ja 、ko 、id 、ru 、ar 、es 、pt-pt 、fr 、de 、th 、tr 、vi 、ta 、it 、bn 、mr |
https |
Boolean | Use https protocol or others |
false |
true . Please set it to true when the project is based on hybrid framework |
timeout |
Number | Duration of request timeout | 30000 (ms) |
Whole numbers greater than zero |
remUnit |
Number | Set the reference value of rem unit | 1 |
remUnit = font-size of root element / DPR(Deivce pixel Ratio) |
zoomEle |
String | If set, the coords will be adjusted along with image scaling | null | Element or id selector. DOM element has to be valid. |
hideSuccess |
Boolean | Hide the verification succeeded message or not | false |
true/false |
hideClose |
Boolean | Hide the close button or not | false |
true/false |
hideRefresh |
Boolean | Hide the refresh button or not | false |
true/false |
api_server |
String | Controls the address of the api request | 'api.geetest.com' |
|
api_server_v3 |
String | Controls the address of the api request |
product
For most of real users, click at the captcha button and then they could pass the captcha test. Suspicious requests will be provided with captcha challenges. GeeTest captcha provides many pop-out styles for captcha challenge.
Four pop-out styles:
popup
(Pop up style)float
(Float style)custom
(Similar withpopup
, but you can custom the pop-out area)bind
(Bind GeeTest captcha button to a custom button, invisible captcha)。
For the custom
style, it’s required to provide an element in the web page as a container for the pop-out challenge. The captcha will be centered within this area. Please configure the following parameters.
Variables | Type | Description |
---|---|---|
area |
String | Set an area for pop-out challenge. The DOM element is required. |
next_width |
String | Width of the pop-out challenge. It could be any length unit supported by css3 , e.g. 260px , 90% . The default width is the 90% of area . |
bg_color |
String | Color of background mask layer. The default color is black. You can set it to any color without opacity. Do not support color in RGBA format. The default opacity is 60%. |
For popup
and bind
style, you could also provide an element in the web page as a container for the pop-out challenge. It’s not required. The captcha challenge will be centered within this area. Please configure the following parameters.
Variables | Type | Description |
---|---|---|
area |
String | Set an area for pop-out challenge. The DOM element is not required. |
next_width |
String | Width of the pop-out challenge. It could be any length unit supported by css3 , e.g. 260px , 90% . The default width is the 90% of area . |
bg_color |
String | Color of background mask layer. The default color is black. You can set it to any color without opacity. Do not support color in RGBA format. The default opacity is 60%. |
For float
style, Please configure the following parameters.
Variables | Type | Description |
---|---|---|
next_width |
String | Width of the pop-out challenge. It could be any length unit supported by css3 , e.g. 260px , 90% . The default width is the 90% of area . |
For the bind
style, the appendTo
API is invalid. Please call verify
method instead to process the verification. Please refer to the example below.
The following section presents examples and demos for each style.
popup
style:
initGeetest({ |
Demo:
Click captcha with popup style
Slide captcha with popup style
float
style:
initGeetest({ |
Demo:
Click captcha with float style
Slide captcha with float style
custom
style
initGeetest({ |
Demo:
Click captcha with custom style
Slide captcha with custom style
bind
style
initGeetest({ |
Demo:
Click captcha with bind style
Slide captcha with bind style
width
Modify the width of captcha button.
Default: 300px * 44px
Notice: the height of the captcha is fixed, the width is modifiable.
Please find the example below. The width of button can be set by width
to fit with input field.
Set the width to 100%
, then the width of the button will be the same as the width of its parent element
initGeetest({ |
Set the width to 20rem
, then the button will be 20 times the width of root element font-size
(CSS property)
initGeetest({ |
lang
GeeTest captcha support for 77 languages. The following are part of the examples.
zh-cn
(Simplified Chinese)zh-tw
(Traditional Chinese, Taiwan)zh-hk
(Traditional Chinese, Hong Kong)en
(English)ja
(Japanese)id
(Indonesian)ko
(Korean)ru
(Russian)ar
(Arabic)es
(Spanish)pt-pt
(Portuguese)fr
(French)de
(German)th
(Thailand)tr
(Turkey)vi
(Vietnam)ta
(Tamil)it
(Italy)bn
(Bangladesh)mr
(Marathi)
Please find the visual presentation of captcha in Chinese and English below.
Simplified Chinese:
English:
Set the captcha language in English
initGeetest({ |
Demo:
Example in English
https
Use https or not. The default value is in consistent with the one used by the webpage in which the captcha has been integrated.
If you want to send https://
captcha request in http://
page or your project is based on hybrid, please refer the following example to set the https://
request.
initGeetest({ |
remUnit
Pass a valid Number type argument. The pixels will be converted into rem based on remUnit. This method applies to H5 page.
remUnit = font-size of root element / DPR(device pixel ratio).
//Assume font-size of root element is 124.2 and DPR is 3. |
zoomEle
Pass an element containing zoom
CSS property or id selector to scale the coordinates to adpat to the page. Please note that the element has to exist and contain zoom
CSS property.
<body style = "zoom: 0.7;" id="zoomEle"> |
initGeetest({ |
hideSuccess
Hide verification succeeded message or not. Boolean value and default is false.
initGeetest({ |
hideClose
Hide close button or not. Boolean value and default is false.
initGeetest({ |
hideRefresh
Hide refresh button or not. Boolean value and default is false.
initGeetest({ |
api_server
Controls the address of the api request.
initGeetest({ |
api_server_v3
Controls the address of the api request.
initGeetest({ |
Instance
Captcha initialization
After initializing captcha with initGeetest
, its second parameter is a callback function. The first parameter of the callback function is the captcha instance. Please find the example below.
initGeetest({ |
API method
appendTo(position)
appendTo
method could insert captcha button into the host page. The input value could be id selector (e.g. #captcha-box
) or DOM element object.
- id selector:
<div id="captcha-box"></div> |
- DOM element
<div id="captcha-box"></div> |
bindForm(position)
The input value type of bindForm
is same as appendTo
. This API could be used to send a new HTTP request with form submit. While sending a new HTTP request with form submit, the bindForm(position)
will insert 3 input tags (see the following html code) into the form.
The following is the sample code:
<div class="geetest_form"> |
The following code is an example to call the bindForm
.
<form id="my-form"> |
After the bindForm
has been called, three input tags will be added to my-form
as shown in the example below.
<form id="my-form"> |
If ajax has been applied to perform the HTTP request, please use the following getValidate
method to get the verification result.
getValidate()
Use getValidate()
if ajax has been applied to perform the HTTP request. Get the verification result from onSuccess
if end user has successfully answer the captcha question. This result could be used to perform secondary verification in server SDK. The getValidate
will return an object, which contains geetest_challenge
, geetest_validate
and geetest_seccode
.
If the verification failed, the onSuccess
will return false
. You can decide to submit form or continue to perform the secondary verification with ajax according to the verification result.
If you call the getValidate
, it will also automatically insert 3 input tags (see the following html example) to the DOM element. If the HTTP request is sent with form submit, use bindForm(position)
method instead of getValidate()
... |
Perform secondary verification with ajax:
initGeetest({ |
reset()
Reset captcha and the verification status will jump to the status that the captcha initialization has finished. It could be used, for example, when usename or password is incorrect but user has passed the captcha test, or error occurs with the captcha.
The following is example that reset the captcha when account or password was incorrect.
initGeetest({ |
verify()
When the pop-out style is set to bind
, call verify()
to process the verification. The verify()
could only be used in bind
.
The advantages for this style is that it allows developers to examine the answer which user fills in the form first. If the answer is okay, then call the API.
<div id="btn">Submit</div> |
onReady(callback)
Listen if the DOM element which contains captcha button is ready.
You can hide the loading prompt of captcha with onReady
event.
<div id="captcha-box"> |
onSuccess(callback)
Listen the verification success event.
Listen the verification success event to perform the secondary verification.
initGeetest({ |
onError(callback)
Listen the verification error event.
You can ask user to reload the webpage and retry the captcha if error occurs. Please find the example below.
initGeetest({ |
onClose(callback)
If the product
is set to bind
, when user closes the captcha challenge, it will trigger the callback function.
initGeetest({ |