Use the reCAPTCHA element to verify that site visitors are human before allowing them to perform restricted operations such as data submission, login, or accessing private content.

Typical CAPTCHA Validation Lifecycle

Important: To ensure complete protection, you must include backend authorization as a mandatory step of the CAPTCHA validation lifecycle.

The following outlines a typical CAPTCHA validation lifecycle:

  1. A button or another clickable element that triggers a submit, login, or another restricted operation is disabled, pending CAPTCHA verification.
  2. A site visitor completes the CAPTCHA challenge. One of the following occurs:
    • Verification: The CAPTCHA is verified. A token is generated. The onVerified() event indicates a successful CAPTCHA challenge completion. Use the onVerified() event handler to enable the disabled clickable element.
    • Error: The reCAPTCHA element loses connection with the CAPTCHA provider. You can use the onError() event handler to instruct the visitor to try again later. Return to Step 1.
  3. The clickable element is enabled. One of the following occurs:
    • Click: The site visitor clicks the clickable element, triggering a backend function that calls authorize() with the generated token.
    • Timeout: The site visitor did not click the submit button within 120 seconds of token generation, causing the token to expire. When timeout occurs, the reCAPTCHA element automatically resets and displays a message asking the site visitor to redo the challenge. Use the onTimeout() event handler to disable the clickable trigger. Return to Step 1.
  4. authorize() checks whether the token is valid. One of the following occurs:
    • Authorization: The CAPTCHA is authorized. Perform the restricted operation (such as data insert) in the backend function. reset() the reCAPTCHA element for future operations.
    • Error: Token fails authorization. reset() the reCAPTCHA element and ask the visitor to redo the challenge. Return to Step 1.

Learn more about working with your reCAPTCHA element.

Note: The reCAPTCHA element does not offer protection for data submission performed via a dataset. To protect data submission with CAPTCHA, use code to perform the data operation (for example, insert() or save()).

Was this helpful?