Skip to content
Picatcha authentication for ruby apps
Pull request Compare This branch is 4 commits ahead, 205 commits behind ambethia:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.




Sean Carey (, Jason L Perry (


Copyright © 2011 Sean Carey, 2007 Jason L Perry






This plugin is based on the work done by Jason L Perry for his reCaptcha plugin, to allow users to integrate Picatcha anti-abuse protection API to your project.

Instead of deciphering garbled text to prove that you are human, Picatcha allows your users to prove they are human by selecting images. 90% of text CAPTCHAs can be defeated by computers leaving your project vulnerable to spam and other internet abuse.

In your views, you can put a +picatcha_+tags method to imbed all the necessary Javascript and HTML into your form. To verify it, use the verify_picatcha in your page's controller.

Before use you must configure Picatcha with your site's private and public keys. These can be obtained at

About this fork

This fork adapts the original recaptcha gem to work with Picatcha's new Image CAPTCHA system.

Rails Installation

Picatcha for Rails, add this to your Gemfile:

gem "picatcha", :require => "picatcha/rails"

Or, it can be installed as a gem:

config.gem "picatcha", :lib => "picatcha/rails"

Or, it can be installed manually (if you downloaded it from our website)

gem install ./picatcha-0.0.1.gem

Or, as a standard rails plugin:

script/plugin install git://

Setting up your API Keys

There are multiple ways to setup your reCAPTCHA API key once you obtain a pair.


You may use the block style configuration. The following code could be placed into a config/initializers/picatcha.rb when used in a Rails project.

Picatcha.configure do |config|
  config.public_key  = '(type in your public key here)'
  config.private_key = '(type in your private key here)'

This way, you may also set additional options to fit Picatcha into your deployment environment.


If you want to temporarily overwrite the configuration you set with `Picatcha.configure` (when testing, for example), you can use a `Picatcha#with_configuration` block:

Picatcha.configure(:public_key => '12345') do
  # Do stuff with the overwritten public_key.

Shell environment

Or, you can keep your keys out of your code base by exporting the following environment variables. You might do this in the .profile/rc, or equivalent for the user running your application:

export RECAPTCHA_PUBLIC_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'

Per call

You can also pass in your keys as options at runtime, for example:

recaptcha_tags :public_key => '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'

and later,

verify_recaptcha :private_key => '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'

This option might be useful, if the same code base is used for multiple reCAPTCHA setups.

To use 'recaptcha'

Add picatcha_tags to each form you want to protect.

And, add verify_picatcha logic to each form action that you've protected. Picatcha will return true for someone who passed, and false for someone who failed.


Some of the options available:


Picatcha currently does not have an


Include <noscript> content (default true)


Takes a hash containing the theme and tabindex options per the API. (default nil)


The ajax option has been disabled, because Picatcha currently does not have an iframe fallback (and therefore requires javascript to generate). This may change in the future as the code evolves.


Your public API key, takes precedence over the ENV variable (default nil)


Override the error code returned from the Picatcha API (default nil)

You can also override the html attributes for the sizes of the generated textarea and iframe elements, if CSS isn't your thing. Inspect the source of recaptcha_tags to see these options.

There are some differences from the reCaptcha gem, first, Picatcha does not have an SSL connection yet. Also, picatcha requires JavaScript to generate the captcha. Those options currently will have no effect, but might be available in the future.


This method returns true or false after processing the parameters from the Picatcha widget. Similar to the reCaptcha gem, it is not a model validation, because that violates MVC. You can use it like this, or how ever you like. Passing in the ActiveRecord object is optional, if you do–and the captcha fails to verify–an error will be added to the object for you to use.

Some of the options available:


Model to set errors


Model attribute to receive errors (default :base)


Custom error message


Your private API key, takes precedence over the ENV variable (default nil).


The number of seconds to wait for Picatcha servers before give up. (default 3)

respond_to do |format|
  if verify_picatcha(:model => @post, :message => "Oh! It's error with Picatcha!") &&
    # ...
    # ...

I18n support

Picatcha passes two types of error explanation to a linked model. It will use the I18n gem to translate the default error message if I18n is available. To customize the messages to your locale, add these keys to your I18n backend:


error message displayed if the captcha words didn't match


displayed if a timout error occured while attempting to verify the captcha


  • Remove Rails/ActionController dependencies

  • Framework agnostic

  • Add some helpers to use in before_filter and what not

  • Better documentation

Something went wrong with that request. Please try again.