Skip to content

Latest commit

 

History

History
142 lines (92 loc) · 6.12 KB

README.rdoc

File metadata and controls

142 lines (92 loc) · 6.12 KB
Raw

Picatcha ↑

Author

Sean Carey (www.picatcha.com), Jason L Perry (ambethia.com)

Copyright

Copyright © 2011 Sean Carey, 2007 Jason L Perry

License

MIT

Info

www.picatcha.com

Git

github.com/naryasece/picatcha/

Bugs

github.com/ambethia/recaptcha/issues

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 www.picatcha.com/signup.

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://github.com/ambethia/recaptcha.git

Setting up your API Keys ↑

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

Picatcha.configure ↑

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)'
end

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

Picatcha#with_configuration ↑

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.
end

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.

picatcha_tags ↑

Some of the options available:

:ssl

Picatcha currently does not have an

:noscript

Include <noscript> content (default true)

:display

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

:ajax

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.

:public_key

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

:error

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.

verify_picatcha ↑

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

Model to set errors

:attribute

Model attribute to receive errors (default :base)

:message

Custom error message

:private_key

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

:timeout

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!") && @post.save
    # ...
  else
    # ...
  end
end

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:

picatcha.errors.verification_failed

error message displayed if the captcha words didn’t match

picatcha.errors.picatcha_unavailable

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

TODO ↑

  • Remove Rails/ActionController dependencies

  • Framework agnostic

  • Add some helpers to use in before_filter and what not

  • Better documentation