Docs
Integrations
Ruby

Ruby

Note

You can also use reCAPTCHA-compatible /siteverify endpoint directly (especially if you already have working reCAPTCHA integration) like in the tutorial example, this SDK is just Python-idiomatic implementation with convenience features.

This is a server-side SDK, which you would use to verify captcha solution against Private Captcha API. This SDK does not solve puzzles on the client side (used to protect APIs).

GitHub repository RubyGems package

Installation

Add this line to your application’s Gemfile:

gem 'private_captcha'

And then execute:

bundle install

Or install it yourself as:

gem install private_captcha

Quick Start 

require 'private_captcha'

# Initialize the client with your API key
client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key-here'
end

# Verify a captcha solution
begin
  result = client.verify('user-solution-from-frontend')
  if result.success
    puts 'Captcha verified successfully!'
  else
    puts "Verification failed: #{result.error_message}"
  end
rescue PrivateCaptcha::Error => e
  puts "Error: #{e.message}"
end

Web Framework Integration

Sinatra Example 

require 'sinatra'
require 'private_captcha'

client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
end

post '/submit' do
  begin
    # Verify captcha from form data
    client.verify_request(request)

    # Process your form data here
    'Form submitted successfully!'
  rescue PrivateCaptcha::Error
    status 400
    'Captcha verification failed'
  end
end

Rails Example 

class FormsController < ApplicationController
  def submit
    client = PrivateCaptcha::Client.new do |config|
      config.api_key = 'your-api-key'
    end

    begin
      client.verify_request(request)
      # Process form data
      render plain: 'Success!'
    rescue PrivateCaptcha::Error
      render plain: 'Captcha failed', status: :bad_request
    end
  end
end

Rack Middleware 

require 'private_captcha'

use PrivateCaptcha::Middleware,
  api_key: 'your-api-key',
  failed_status_code: 403

Configuration

Client Options 

require 'private_captcha'

client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # replace domain for self-hosting or EU isolation
  config.form_field = 'private-captcha-solution'            # custom form field name
  config.max_backoff_seconds = 20                           # maximum wait between retries
  config.attempts = 5                                       # number of retry attempts
  config.logger = Logger.new(STDOUT)                        # optional logger
end

Non-standard backend domains 

require 'private_captcha'

# Use EU domain
eu_client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = PrivateCaptcha::Configuration::EU_DOMAIN  # api.eu.privatecaptcha.com
end

# Or specify custom domain in case of self-hosting
custom_client = PrivateCaptcha::Client.new do |config|
  config.api_key = 'your-api-key'
  config.domain = 'your-custom-domain.com'
end

Retry Configuration 

result = client.verify(
  'solution',
  max_backoff_seconds: 15,  # maximum wait between retries
  attempts: 3               # number of retry attempts
)
Last updated on
WordPress