Hcaptcha

Ruby gem made to use Hcaptcha bot protection in your applications. Official documentation is available here

Installation

Add this line to your application's Gemfile:

gem 'hcaptcha'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install hcaptcha

Configuration

Create an account on Hcaptcha website and ask for API keys.

And then add an initializer

# config/initializers/hcaptcha.rb

Hcaptcha.configure do |config|
  config.site_key = 'YOUR_PUBLIC_SITE_KEY'
  config.secret_key = 'YOUR_SECRET_KEY'
  # optional, default value = https://hcaptcha.com/siteverify
  config.verify_url = 'VERIFY_URL'
  # optional, default value = https://hcaptcha.com/1/api.js
  config.api_script_url = 'API_SCRIPT_URL'
end

Usage

An h-captcha-response will be generated by inserting hcaptcha_tag inside your form. You must validate this token in your controller method with verify_hcaptcha method.

exemple:

# app/views/foos/new.html.erb
<form>
  ...
  <%= hcaptcha_tag %>

  [submit]
</form>

# app/controllers/foos_controller.rb

...
  def create
    captcha_validated, captcha_response = verify_hcaptcha
    if captcha_validated
      [Your code goes here]
    else
      flash[:error] = captcha_response[:error_codes]
      render :new
    end
  end
...

This GEM has been made to be used inside Rails applications but can also be used in standard ruby applications. You can call Hcaptcha.api_verification(token) to get a verfication from hcaptcha API. The verification token can be obtained by following hcaptcha documentation in your html views or by using this gem form helper after requiring and including mandatory files and modules like so:

require 'hcaptcha/helpers/form_helper'

include Hcaptcha::Helpers::FormHelper

hcaptcha_tag(**options) # will return an html string with required input and script

Invisible Hcaptcha

To use invisible Hcaptcha, simply add option size: invisible to hcaptcha_tag method call. This will create an invisible input that, on submit of your form, will request a token to hcaptcha. As of Hcapthca documentation, the user will only be presented with a hCaptcha challenge if that user has not built up enough trust.

⚠️ Since Rails >= 5, submit buttons are automatically binded with a data-disabled-with attribute. As invisible hcaptcha will be binded on your form submit button, you should disable this option otherwise if a Challenge is requested and the user close it, he will not be able to submit again the form. You can disable it either globally in your app like so

config.action_view.automatically_disable_submit_tag = false

or, to do it ad-hoc for specific buttons, add this option to the submit button

data: { disable_with: false }

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hcaptcha. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Hcaptcha project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.