FriendlyCaptcha Ruby Gem

A Ruby gem for integrating Friendly Captcha v2 into your Ruby and Rails applications. Friendly Captcha is a privacy-first, GDPR-compliant captcha service that protects your websites from spam and abuse without tracking users or requiring them to solve puzzles.

Features

Privacy-First: No user tracking or data collection
Accessibility: Works seamlessly for all users
Easy Integration: Drop-in replacement for other captcha services
Rails Support: Built-in helpers for Rails applications
v2 API: Uses the latest Friendly Captcha v2 API

Installation

Add this line to your application's Gemfile:

gem 'friendly_captcha'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install friendly_captcha

Setup

1. Get Your Keys

Sign up for a Friendly Captcha account
Create a new application to get your:
- Site Key (for frontend widget)
- API Key (for backend verification)

2. Configure the Gem

Create an initializer file config/initializers/friendly_captcha.rb:

FriendlyCaptcha.configure do |config|
  config.api_key = ENV['FRIENDLY_CAPTCHA_API_KEY']    # Your API key
  config.site_key = ENV['FRIENDLY_CAPTCHA_SITE_KEY']  # Your site key
  
  # Optional: Use EU endpoint for GDPR compliance
  # config.verification_endpoint = FriendlyCaptcha.config.eu_endpoint
  
  # Optional: Enable strict mode (reject when verification fails)
  # config.strict_mode = true
end

Usage

In Views (Rails)

Add the captcha widget to your forms:

<%= form_with url: "/submit" do |form| %>
  <%= form.text_field :email, placeholder: "Email" %>
  
  <!-- Add the Friendly Captcha widget -->
  <%= friendly_captcha %>
  
  <%= form.submit "Submit" %>
<% end %>

Customization Options

<!-- Basic usage -->
<%= friendly_captcha %>

<!-- With custom options -->
<%= friendly_captcha(
  sitekey: "your-custom-site-key",  # Override default site key
  start: "focus",                   # auto, focus, or none
  lang: "de",                       # Language code
  form_field_name: "custom-field"   # Custom form field name
) %>

In Controllers (Rails)

Verify the captcha response in your controller:

class ContactController < ApplicationController
  def create
    result = verify_friendly_captcha
    
    if result[:success]
      # Captcha verification successful
      # Process the form...
      redirect_to success_path, notice: "Thank you for your submission!"
    else
      # Captcha verification failed
      flash.now[:error] = "Please complete the captcha verification."
      render :new
    end
  end
end

Advanced Verification

# With custom options
result = verify_friendly_captcha(
  api_key: "custom-api-key",
  sitekey: "custom-site-key",
  field_name: "custom-field-name",
  endpoint: FriendlyCaptcha.config.eu_endpoint
)

# Check the result
if result[:success]
  puts "Verification successful!"
  puts "Challenge timestamp: #{result[:challenge_timestamp]}" if result[:challenge_timestamp]
else
  puts "Verification failed: #{result[:error]}"
  puts "Error code: #{result[:error_code]}" if result[:error_code]
  puts "Fallback mode: #{result[:fallback]}" if result[:fallback]
end

Non-Rails Usage

For non-Rails Ruby applications:

require 'friendly_captcha'

# Configure
FriendlyCaptcha.configure do |config|
  config.api_key = "your-api-key"
  config.site_key = "your-site-key"
end

# Generate widget HTML
include FriendlyCaptcha::ViewHelpers
widget_html = friendly_captcha

# Verify response (in your request handler)
include FriendlyCaptcha::ControllerHelpers

# Mock params for non-Rails usage
def params
  { 'frc-captcha-response' => 'user-response-token' }
end

result = verify_friendly_captcha

Configuration Options

Option	Description	Default
`api_key`	Your Friendly Captcha API key	`nil`
`site_key`	Your Friendly Captcha site key	`nil`
`verification_endpoint`	API endpoint for verification	`https://global.frcapi.com/api/v2/captcha/siteverify`
`eu_endpoint`	EU-only API endpoint	`https://eu.frcapi.com/api/v2/captcha/siteverify`
`strict_mode`	Reject when verification fails	`false`
`source`	Modern widget script URL	Latest v2 SDK
`source_compat`	Legacy browser script URL	Latest v2 SDK

Widget Options

Attribute	Description	Default
`sitekey`	Your site key	From config
`start`	When to start solving (`auto`, `focus`, `none`)	`auto`
`lang`	Language code (e.g., `en`, `de`, `fr`)	Auto-detected
`form_field_name`	Name of the hidden form field	`frc-captcha-response`

Error Handling

The gem includes intelligent error handling:

Non-strict mode (default): If verification fails due to network issues or API problems, the captcha is accepted to avoid blocking legitimate users
Strict mode: All captcha responses must be successfully verified

# Enable strict mode
FriendlyCaptcha.configure do |config|
  config.strict_mode = true
end

Testing

In your test environment, you might want to bypass captcha verification:

# In test environment
if Rails.env.test?
  # Mock successful verification
  allow_any_instance_of(FriendlyCaptcha::ControllerHelpers)
    .to receive(:verify_friendly_captcha)
    .and_return({ success: true })
end

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.

To install this gem onto your local machine, run bundle exec rake install.

Migration from v1

If you're upgrading from Friendly Captcha v1:

Update your API keys in the dashboard
Change form field name from frc-captcha-solution to frc-captcha-response
Update your configuration to use api_key instead of secret
The widget will automatically use the new v2 scripts

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hendrixfan/friendly_captcha. 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 FriendlyCaptcha project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.