# reCAPTCHA
[![Gem Version](https://badge.fury.io/rb/recaptcha.svg)](https://badge.fury.io/rb/recaptcha)

Author:    Jason L Perry (http://ambethia.com)

Copyright: Copyright (c) 2007-2013 Jason L Perry

License:   [MIT](http://creativecommons.org/licenses/MIT/)

Info:      https://github.com/ambethia/recaptcha

Bugs:      https://github.com/ambethia/recaptcha/issues


This gem provides helper methods for the [reCAPTCHA API](https://www.google.com/recaptcha). In your
views you can use the `recaptcha_tags` method to embed the needed javascript, and you can validate
in your controllers with `verify_recaptcha` or `verify_recaptcha!`, which raises an error on
failure.


# Table of Contents
1. [Obtaining a key](#obtaining-a-key)
2. [Rails Installation](#rails-installation)
3. [Sinatra / Rack / Ruby Installation](#sinatra--rack--ruby-installation)
4. [reCAPTCHA V2 API & Usage](#recaptcha-v2-api-and-usage)
  - [`recaptcha_tags`](#recaptcha_tags)
  - [`verify_recaptcha`](#verify_recaptcha)
  - [`invisible_recaptcha_tags`](#invisible_recaptcha_tags)
5. [reCAPTCHA V3 API & Usage](#recaptcha-v3-api-and-usage)
  - [`recaptcha_v3`](#recaptcha_v3)
  - [`verify_recaptcha` (use with v3)](#verify_recaptcha-use-with-v3)
  - [`recaptcha_reply`](#recaptcha_reply)
6. [I18n Support](#i18n-support)
7. [Testing](#testing)
8. [Alternative API Key Setup](#alternative-api-key-setup)

## Obtaining a key

Go to the [reCAPTCHA admin console](https://www.google.com/recaptcha/admin) to obtain a reCAPTCHA API key.

The reCAPTCHA type(s) that you choose for your key will determine which methods to use below.

| reCAPTCHA type                               | Methods to use | Description |
|----------------------------------------------|----------------|-------------|
| v3                                           | [`recaptcha_v3`](#recaptcha_v3)                         | Verify requests with a [score](https://developers.google.com/recaptcha/docs/v3#score)
| v2 Checkbox
("I'm not a robot" Checkbox) | [`recaptcha_tags`](#recaptcha_tags)                     | Validate requests with the "I'm not a robot" checkbox |
| v2 Invisible
(Invisible reCAPTCHA badge) | [`invisible_recaptcha_tags`](#invisible_recaptcha_tags) | Validate requests in the background |

Note: You can _only_ use methods that match your key's type. You cannot use v2 methods with a v3
key or use `recaptcha_tags` with a v2 Invisible key, for example. Otherwise you will get an
error like "Invalid key type" or "This site key is not enabled for the invisible captcha."

Note: Enter `localhost` or `127.0.0.1` as the domain if using in development with `localhost:3000`.

## Rails Installation

```ruby
gem "recaptcha"
```

You can keep keys out of the code base with environment variables or with Rails [secrets](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-secrets).


In development, you can use the [dotenv](https://github.com/bkeepers/dotenv) gem. (Make sure to add it above `gem 'recaptcha'`.)

See [Alternative API key setup](#alternative-api-key-setup) for more ways to configure or override
keys. See also the
[Configuration](https://www.rubydoc.info/github/ambethia/recaptcha/master/Recaptcha/Configuration)
documentation.

```shell
export RECAPTCHA_SITE_KEY   = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
export RECAPTCHA_SECRET_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
```

If you have an Enterprise API key:

```shell
export RECAPTCHA_ENTERPRISE            = 'true'
export RECAPTCHA_ENTERPRISE_API_KEY    = 'AIzvFyE3TU-g4K_Kozr9F1smEzZSGBVOfLKyupA'
export RECAPTCHA_ENTERPRISE_PROJECT_ID = 'my-project'
```

Add `recaptcha_tags` to the forms you want to protect:

```erb
<%= form_for @foo do |f| %>
  # …
  <%= recaptcha_tags %>
  # …
<% end %>
```

Then, add `verify_recaptcha` logic to each form action that you've protected:

```ruby
# app/controllers/users_controller.rb
@user = User.new(params[:user].permit(:name))
if verify_recaptcha(model: @user) && @user.save
  redirect_to @user
else
  render 'new'
end
```
Please note that this setup uses [`reCAPTCHA_v2`](#recaptcha-v2-api-and-usage). For a `recaptcha_v3` use, please refer to [`reCAPTCHA_v3 setup`](#examples).

## Sinatra / Rack / Ruby installation

See [sinatra demo](/demo/sinatra) for details.

 - add `gem 'recaptcha'` to `Gemfile`
 - set env variables
 - `include Recaptcha::Adapters::ViewMethods` where you need `recaptcha_tags`
 - `include Recaptcha::Adapters::ControllerMethods` where you need `verify_recaptcha`


## reCAPTCHA v2 API and Usage

### `recaptcha_tags`

Use this when your key's reCAPTCHA type is "v2 Checkbox".

The following options are available:

| Option              | Description |
|---------------------|-------------|
| `:theme`            | Specify the theme to be used per the API. Available options: `dark` and `light`. (default: `light`) |
| `:ajax`             | Render the dynamic AJAX captcha per the API. (default: `false`) |
| `:site_key`         | Override site API key from configuration |
| `:error`            | Override the error code returned from the reCAPTCHA API (default: `nil`) |
| `:size`             | Specify a size (default: `nil`) |
| `:nonce`            | Optional. Sets nonce attribute for script. Can be generated via `SecureRandom.base64(32)`. (default: `nil`) |
| `:id`               | Specify an html id attribute (default: `nil`) |
| `:callback`         | Optional. Name of success callback function, executed when the user submits a successful response |
| `:expired_callback` | Optional. Name of expiration callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |
| `:error_callback`   | Optional. Name of error callback function, executed when reCAPTCHA encounters an error (e.g. network connectivity) |
| `:noscript`         | Include `