fokayx/reCAPTCHA.md

## reCAPTCHA.md

      
    Raw
  

              reCAPTCHA.md
            
          
    #reCAPTCHA for Rails > 3.0

目前的reCAPTCHA版本已不支援Rails 3.0以下的專案，如果你的專案用的是Rails 3.0以下，你可以去找reCAPTCH過去發佈的版本，並按照說明進行安裝。
reCAPTCHA @ GitHub: https://github.com/ambethia/recaptcha

##Rails安裝方法
打開 Gemfile，加入recaptcha。
gem "recaptcha", :requier => "recaptcha/rails"

###設定你的reCAPTCHA API Keys
如果你尚未註冊過，請到Google reCAPTCHA為你的網站申請。
Label: 設定一個標籤，方便進行辨識與管理。
範例：(網址: 說明) => example.com: user registering
Domains: 相連的域名都要一起加進來進行註冊，例如subdomain.domain.com，一行寫一個域名，不需要寫到path。
如果所填寫的域名和reCAPTCHA API Key配不起來的話，就會出現internal error occurred recaptcha… 的錯誤訊息。

填寫完Label、Domain，按下Register進行註冊，就會為你的網站產生一組reCAPTCHA設定，包含Site key、Secret key、js、reCAPTCHA widget。
###reCAPTCHA 設置
在Rails專案中新增reCAPTCHA的設定檔：config/initializers/recaptcha.rb，並設定reCAPTCHA API Key。
Recaptcha.configure do |config|
    config.public_key = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
    config.private_key = '6Lc6BAAAAAAAAChqRbQZcn_xxxxxxxxxxxxxxxx'
    # Uncomment the following line if you are using a proxy server:
    # config.proxy = 'http://myproxy.com.au:8080'
    # Uncomment if you want to use the newer version of the API,
    # only works for versions >= 0.3.7:
    # config.api_version = 'v2'
end

# 如果是使用Google reCAPTCHA：config.public_key = 'Site key'，config.private_key = 'Secret key'

###reCAPTCHA API Key 保護
如果會將專案推到GitHub或作公開分享，為了保護自己的reCAPTCHA API Key，可以這麼做。
# config/initializers/recaptcha.rb
Recaptcha.configure do |config|
    config.public_key = ENV["RECAPTCHA_PUBLIC_KEY"]
    config.private_key = ENV["RECAPTCHA_PRIVATE_KEY"]
end

# config/secrets.yml
production:
  recaptcha_public_key: <%= ENV["RECAPTCHA_PUBLIC_KEY"] %>
  recaptcha_secret_key: <%= ENV["RECAPTCHA_PRVATE_KEY"] %>

###Sever Shell 環境設定 reCAPTCHA API Key
export RECAPTCHA_PUBLIC_KEY = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAChqRbQZcn_xxxxxxxxxxxxxxxx'

###Heroku設定 reCAPTCHA API Key
如果是要佈署到Heroku上，為了要保密 reCAPTCHA API Key，可以用下列方法設定 RECAPTCHA_PUBLIC_KEY、RECAPTCHA_PRIVATE_KEY。
heroku config:set RECAPTCHA_PUBLIC_KEY = "YOUR PUBLIC KEY"
heroku config:set RECAPTCHA_PRIVATE_KEY = "YOUR PRIVATE KEY"

###在網頁中使用reCAPTCHA
在網站需要做驗証的頁面中加入recaptcha_tags。
<%= form_for @foo do |f| %>
    #......
    <%= recaptcha_tags %>
    #......
<% end %>

###recaptcha_tags 屬性
:ssl
:noscript (引入 <noscript>內容，預設 true。)
:display (theme和 tabindex的選項設定，預設 nil，選項有 'red', 'white', 'blackglass', 'clean', 'custom'。 ex: :display => {:theme => 'white'} )
:ajax (使用動態AJAX captcha，預設 false。)
:public_key (Site key設定，優先使用 ENV中的參數設定，預設nil。)
:error (Override the error code returned from the reCAPTCHA API (default nil)

###reCAPTCHA進行驗証：verify_recaptcha
接著在要驗証的controller action，寫入 verify_recaptcha。
經過reCAPTCAH驗証後會回傳true或false。
# 以發佈文章為例
class PostController < ApplicationController
    def create
        @post = Post.new
        if verify_recaptcha(:model => @post, :message => "OH, NO! It's error with reCAPTCHA") && @post.save
            #...(通過驗証)
        else
            #...(驗証失敗)
        end
    end
end

設定參數：
:model (Model to set errors)
:attribute (Model attribute to receive errors (default :base))
:message (客製化錯誤訊息。)
:private_key (設定Secret API key,會優先使用 ENV中的參數設定，預設 `nil`。)
:timeout (等待reCAPTCHA服務的時間，預設是 3秒。)

###l18n 支援
reCAPTCHA提供2種錯誤訊息，如果專案中有安裝 l18n， l18n將會直接對預設的錯誤訊息進行翻譯。如果想客製化訊息，需要在l18n backend中加入下列代碼：
recaptcha.errors.verification_failed (當使用者輸入不符合 captcha，顯示錯誤訊息)
recaptcha.errors.recaptcha_unreachable (在驗証captcha時，如果發生timeout，顯示錯誤訊息)

編輯客製化錯誤訊息：
# config/locales/en.yml
en:
    recaptcha:
        errors:
            incorrect-captcha-sol: 'Fail'