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
BotDetect client-side prototype public function Init
  • captchaId
  • instanceId
  • inputId
  • autoUppercaseInput
  • autoFocusInput
  • autoClearInput
  • autoReloadExpiredImage
  • autoReloadPeriod
  • autoReloadTimeout
  • soundStartDelay
  • limitSoundRegeneration

The client-side BotDetect initialization function (used as a "constructor") takes the following arguments:

  • captchaId is the unique Captcha identifier of the Captcha control on the page. It's a mandatory parameter for all Captcha scripts to run
  • instanceId is the unique identifier of each Captcha instance (each Captcha identified by captchaId generates a new instanceId every time it generates its markup i.e. on each page load)
  • inputId is the client-side identifier of the Captcha code user input field. It's needed for all scripts that process the user input
  • autoUppercaseInput is a boolean value specifying if the user input should be automatically uppercased during typing
  • autoFocusInput is a boolean value specifying if the user input should be automatically focused on Captcha Reload and Sound button clicks
  • autoClearInput is a boolean value specifying if the user input should be automatically cleared on Captcha Reload button clicks
  • autoReloadExpiredImage is a boolean value specifying if Captcha images displaying expired Captcha codes should be automatically reloaded
  • autoReloadPeriod is the millisecond count equivalent of the Captcha code timeout value
  • autoReloadTimeout is the upper bound millisecond count, after which automatic reloading will stop. This is used to save resources and stop generating Captchas if the user leaves the form open during the weekend and leaves town, for example
  • soundStartDelay is the starting delay (in milliseconds) for JavaScript Captcha sound playback
  • limitSoundRegeneration tells BotDetect to count sound icon clicks in browsers that don't support Html5 Wav audio, and reload the Captcha image before playing the Captcha audio on sound icon clicks after the first one. This is needed when using the "LIMITED" sound regeneration mode
BotDetect client-side prototype public function RegisterCustomHandler
  • eventName
  • userHandler

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

BotDetect client-side prototype constant value ReloadTimerDelay = 250 The delay between each Captcha Reload animation "tick" (status update), in milliseconds.
BotDetect client-side prototype constant value 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).
BotDetect client-side prototype constant value 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.
BotDetect client-side prototype constant value 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:

  • using this.<member_name> within member functions and custom event handlers.

    E.g. if you register a function as a custom handler for the PreReloadImage BotDetect event, you can access the BotDetect client-side object within that function using this.

  • 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 formCaptcha as the client-side Captcha object identifier.

  • using the Captcha custom 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: document.getElementById("captchaCode").Captcha.

    Or, if you're using jQuery and (for example) added a "captchaVal" CSS class to the Captcha code textbox, you can use: $(".captchaVal").get(0).Captcha.

BotDetect Client-Side Object Reference
BotDetect client-side object function ReloadImage Reloads the current Captcha client-side instance Captcha image
BotDetect client-side object function PlaySound Starts Captcha sound playback for the current Captcha client-side instance
BotDetect client-side object function StartAjaxValidation Starts Ajax validation of the user input for the current Captcha client-side instance
BotDetect client-side object value Id The Captcha Id for the current object (same as the server-side object)
BotDetect client-side object value InstanceId The Instance Id for the current object (same as the server-side object)
BotDetect client-side object value Image The <img> element containing the Captcha image
BotDetect client-side object value InputId The element identifier of the Captcha code user input field (usually a <input type="text" ... /> element). Only set if the user input client-side ID was specified in the constructor
BotDetect client-side object function GetInputElement Related to the above, tries to get the input element by Id
BotDetect client-side object value ProgressIndicator The text element created during Captcha image reloading, and used as a Reload progress indicator
BotDetect client-side object value AutoReloading Flag indicating that the Captcha image is currently being reloaded because the automatic reloading timer has activated
BotDetect client-side object value SoundPlaceholder The invisible <div> element used as a container for sound objects created during Captcha sound playback
BotDetect client-side object value SoundUrl BotDetect Captcha Sound Url, used during sound playback
BotDetect client-side object value 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)
BotDetect client-side object value ValidationResult Set during Ajax Captcha validation
BotDetect client-side custom event PostInit This event occurs after the BotDetect client-side object has been successfully initialized
BotDetect client-side custom event PreReloadImage

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)

BotDetect client-side custom event PostReloadImage

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)

BotDetect client-side custom event PrePlaySound

This event occurs after the user clicks the Captcha Sound button, but before sound playing starts.

Note that there is no matching PostPlaySound event, since the available client-side sound playback options don't notify calling functions when playback ends

BotDetect client-side custom event OnHelpLinkClick

This event occurs when the user clicks the Captcha image when it's also the Captcha help link (the Image help link mode). Captcha help page opening can be aborted in this handler by setting the BotDetect client-side object's FollowHelpLink property to false

BotDetect client-side custom event PreAjaxValidate This event occurs after the BotDetect client-side Validate() function is called, but before any Ajax calls are made
BotDetect client-side custom event AjaxValidationFailed

This event occurs after BotDetect Ajax Captcha validation returns false.

The default handler reloads the Captcha image, since Captcha validation has invalidated the currently displayed Captcha code on the server

BotDetect client-side custom event AjaxValidationPassed This event occurs after BotDetect Ajax Captcha validation returns true
BotDetect client-side custom event AjaxValidationError

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 true to enable full page postback


Please Note

BotDetect Java Captcha Library v4.0.Beta1 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.