I Can't Work Out Where to Add reCAPTCHA

This advice applies to everyone who's integrating reCAPTCHA -- irrespective of language.

Firstly you need to identify two hot spots in your code. These are the places where you'll be adding the reCAPTCHA calls.

  • Display reCAPTCHA: The first hot spot is the code that generates the form. Hopefully that's easy enough to find (by looking for a <form> tag in your html) and you have been able to display the CAPTCHA on your form.

  • Check reCAPTCHA: The second hot spot is the one that seems to cause people problems. You need to identify the code that handles form submission -- that is the code that runs when the user clicks on submit. It's hard to generalize about what this code looks like but here are some clues that may help you:

    • if your form can ever display an error message, for example if a required field is blank, look for the code that generates that error message.
    • if your form places information in a database look for code that does a SQL INSERT.
    • if your form sends mail, search for the code that does that.

    Form Already Has Validation

    Life will be easier if your form already has some validation logic (i.e. it handles invalid input from the user by displaying a message instead of performing whatever action it normally would). If that's the case and you can find the code that does that you're nearly home free. If the form can display an error message search for the text of the error message within the code and you're sure to be close. Once you've found the validation code you need to add a call to the check_answer function in addition to whatever other checks are there (email address blank? age too young? etc.).

    Form Has No Validation

    If there's currently no validation logic for your form -- if clicking on submit always succeeds -- then you have a more tricky problem. In that case you'll have to add the reCAPTCHA validation code right before the existing form handling code does whatever it does when the user submits. You'll also have to figure out how to redisplay the form to give the user another attempt at the captcha. Unfortunately there's no one stock answer to how you do that. It depends entirely on the structure of the code you already have. If the existing code isn't too complex you may have luck posting it on the reCAPTCHA developer forum and asking for advice. (If you do post there, be sure to include enough information for others to help you; simply saying "my code doesn't work" usually doesn't yield good results.)

  • It's Not Working! Help!

    Before doing anything else make sure you're using the correct keys. Are your public and private keys swapped? Did you remember to put the private key in the form handler as well as putting the public key in the form?

    Note that Mailhide uses different keys from the main form-based reCAPTCHA.

    Be sure that your form uses the POST method, or else change the reCAPTCHA form handler variables to GET instead of POST.

    If reCAPTCHA was working and you suddenly start getting "An internal error occurred", did you recently delete the Google account that you used to sign up for the keys? If so, register for new keys with an active account and try those.

    reCAPTCHA is Accepting Incorrect Words

    One of the words displayed by reCAPTCHA is from an old book which is being digitized. As such it is not graded -- it cannot. Indeed, occasionally it may be blank, or just a bit of noise.

    On the word that is checked, the user is (by default) allowed to be off by one letter. It has been found that this increases the user experience while not degrading security by a large amount. This is tuned dynamically based on many factors.

    No, I Mean *Totally* Incorrect Words

    If reCAPTCHA is accepting any input whatsoever, you probably aren't correctly validating the reCAPTCHA answer with the API servers. That is, either: (1) you are not correctly calling (or the equivalent function if you're using a plugin, such as recaptcha_check_answer in PHP), or (2) you are not taking the appropriate action given the response from our servers. Please see the specific instructions that you used to install reCAPTCHA (whether it be through a plugin or not) to learn how to check whether the user entered the answer correctly.

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.