hCaptcha

• https://github.com/Retrospring/hcaptcha
• https://github.com/firstmoversadvantage/hcaptcha
• https://github.com/ambethia/recaptcha

License: MIT
Bugs: https://github.com/firstmoversadvantage/hcaptcha/issues

This gem provides helper methods for the hCaptcha API. In your views you can use the hcaptcha_tags method to embed the needed javascript, and you can validate in your controllers with verify_hcaptcha or verify_hcaptcha!.

Go to the hCaptcha signup page to obtain API keys. You'll also need to set a hostname that your application will run from, even for local development. hCaptcha will not work if your application is being served from localhost or 127.0.0.1. You will need to add a hosts entry for local development. See the hCaptcha docs for how to do this.

The hostname you set it to must be a real hostname, since hCaptcha validates it when you create it in the portal. For example, example.fmadata.com does not have a DNS record, but mydomain.com does. The DNS record doesn't need to point to your application though, it just has to exist - that's why we added the record into the local hosts file.

FIrst, add the gem to your bundle:

bundle add hcaptcha

Then, set the following environment variables:

• HCAPTCHA_SECRET_KEY
• HCAPTCHA_SITE_KEY

💡 You should keep keys out of your codebase with external environment variables (using your shell's export command), Rails (< 5.2) secrets, Rails (5.2+) credentials, the dotenv or figaro gems, …

First, add hcaptcha_tags to the forms you want to protect:

<%= form_for @foo do |f| %>
  # …
  <%= hcaptcha_tags %>
  # …
<% end %>

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

# app/controllers/users_controller.rb
@user = User.new(params[:user].permit(:name))
if verify_hcaptcha(model: @user) && @user.save
  redirect_to @user
else
  render 'new'
end

If you are not using Rails, you should:

• include Hcaptcha::Adapters::ViewMethods where you need recaptcha_tags
• include Hcaptcha::Adapters::ControllerMethods where you need verify_hcaptcha

Use in your views to render the JavaScript widget.

Available options:

ℹ️ Unkown options will be passed directly as attributes to the placeholder element.

For example, hcaptcha_tags(foo: "bar") will generate the default script tag and the following placeholder tag:

<div class="h-captcha" data-sitekey="…" foo="bar"></div>

This method returns true or false after processing the response token from the hCaptcha widget. This is usually called from your controller.

Passing in the ActiveRecord object via model: object is optional. If you pass a model—and the captcha fails to verify—an error will be added to the object for you to use (available as object.errors).

Why isn't this a model validation? Because that violates MVC. You can use it like this, or how ever you like.

Some of the options available:

hCaptcha supports the I18n gem (it comes with English translations) To override or add new languages, add to config/locales/*.yml

# config/locales/en.yml
en:
  recaptcha:
    errors:
      verification_failed: 'hCaptcha was incorrect, please try again.'
      recaptcha_unreachable: 'hCaptcha verification server error, please try again.'

By default, hCaptcha is skipped in "test" and "cucumber" env. To enable it during test:

Hcaptcha.configuration.skip_verify_env.delete("test")