BotDetect Java CAPTCHA Client-Side API Reference
BotDetect Client-Side Prototype Reference
The main client-side BotDetect prototype (accessible on the whole page using
BotDetect.<member_name>) exposes several global functions and constants.
|BotDetect Client-Side Prototype Reference|
The client-side BotDetect initialization function (used as a "constructor") takes the following arguments:
This function is used to register a user-defined handler function, which will be called by BotDetect any time the specified BotDetect event occurs.
The first parameter is the name of the BotDetect event you want to handler, and the second is the (parameter-less) handler function that should be called
|ReloadTimerDelay = 250||The delay between each Captcha Reload animation "tick" (status update), in milliseconds.|
|ReloadTimerMaxTicks = 100||The maximum number of "ticks" the Captcha Reload animation will go through before it stops (in case the Captcha image reloading Http request timeouts or fails to return a new image).|
|MinSoundCooldown = 2000||The cooldown applied to Captcha sound icon clicks, in milliseconds. Used to reduce chances of the user accidentaly starting multiple concurrent Captcha sound playbacks.|
|AjaxTimeout = 10000||The maximum time (in milliseconds) spent waiting for server responses to asynchronous Http requests. After this period, an Ajax error is raised|
BotDetect Client-Side Object Reference
BotDetect client-side object instances expose all Captcha workflow functions and values, as well as several Captcha life-cycle events. These objects can be accessed in your client-side scripts:
this.<member_name>within member functions and custom event handlers.
E.g. if you register a function as a custom handler for the
PreReloadImageBotDetect event, you can access the BotDetect client-side object within that function using
<captchaId>.<member_name>on the page showing the Captcha.
E.g. if you added Captcha protection to a Java form using
Captcha captcha = Captcha.load(request, "formCaptcha"), you can also use
formCaptchaas the client-side Captcha object identifier.
Captchacustom property of the textbox DOM element registered as the Captcha code input.
E.g. if your server-side code specifies
captcha.setUserInputID("captchaCode"), your client-side code can access Captcha functionality through the textbox element:
Or, if you're using jQuery and (for example) added a
"captchaVal"CSS class to the Captcha code textbox, you can use:
|BotDetect Client-Side Object Reference|
|ReloadImage||Reloads the current Captcha client-side instance Captcha image|
|PlaySound||Starts Captcha sound playback for the current Captcha client-side instance|
|StartAjaxValidation||Starts Ajax validation of the user input for the current Captcha client-side instance|
|Id||The Captcha Id for the current object (same as the server-side object)|
|InstanceId||The Instance Id for the current object (same as the server-side object)|
|Image||The <img> element containing the Captcha image|
|InputId||The element identifier of the Captcha code user input field (usually a
|GetInputElement||Related to the above, tries to get the input element by Id|
|ProgressIndicator||The text element created during Captcha image reloading, and used as a Reload progress indicator|
|AutoReloading||Flag indicating that the Captcha image is currently being reloaded because the automatic reloading timer has activated|
|SoundUrl||BotDetect Captcha Sound Url, used during sound playback|
|ValidationUrl||The Url that can be used to send an Ajax Captcha validation request (with the user input of the Captcha code appended as an additional querystring parameter)|
|ValidationResult||Set during Ajax Captcha validation|
|PostInit||This event occurs after the BotDetect client-side object has been successfully initialized|
This event occurs after the user clicks the Captcha Reload button, but before image reloading starts.
The default handler clears previous user input, and focuses the Captcha code input field (if auto-clearing and auto-focusing are enabled)
This event occurs after the Captcha image has been successfully reloaded.
The default handler updates the Captcha sound Url, and sets up automatic image reloading (if auto-reloading is enabled and we haven't reached the timeout threshold)
This event occurs after the user clicks the Captcha Sound button, but before sound playing starts.
Note that there is no matching
This event occurs when the user clicks the Captcha image when it's also the Captcha help link (the
|PreAjaxValidate||This event occurs after the BotDetect client-side
This event occurs after BotDetect Ajax Captcha validation returns
The default handler reloads the Captcha image, since Captcha validation has invalidated the currently displayed Captcha code on the server
|AjaxValidationPassed||This event occurs after BotDetect Ajax Captcha validation returns
This event occurs if BotDetect Ajax Captcha validation throws errors or timeouts.
The default handler aborts any Ajax operations left, and sets the AjaxError flag, which in turn temporarily sets the validation result to
BotDetect Java Captcha Library v4.0.Beta2 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.