1Captcha::reCAPTCHA(3) User Contributed Perl DocumentationCaptcha::reCAPTCHA(3)
2
6 Captcha::reCAPTCHA - A Perl implementation of the reCAPTCHA API
7
9 This document describes Captcha::reCAPTCHA version 0.99
10
12 Please note this module now allows the use of v2 there are no changes
13 to version 1. Version 2 has seperate methds you can call
14
16 Note this release contains methods that use
17 use Captcha::reCAPTCHA;
19 my $c = Captcha::reCAPTCHA->new;
21 # Output form New Version
23 print $c->get_html_v2( 'your public key here' );
24 # Version 1 (not recommended)
26 print $c->get_html( 'your public key here' );
27 # Verify submission
29 my $result $c->check_answer_v2($private_key, $response, $ENV{REMOTE_ADDR});
30 # Verify submission (Old Version)
32 my $result = $c->check_answer(
33 'your private key here', $ENV{'REMOTE_ADDR'},
34 $challenge, $response
35 );
36 if ( $result->{is_valid} ) {
38 print "Yes!";
39 }
40 else {
41 # Error
42 $error = $result->{error};
43 }
44 For complete examples see the /examples subdirectory
46
48 reCAPTCHA version 1 is a hybrid mechanical turk and captcha that allows
49 visitors who complete the captcha to assist in the digitization of
50 books.
51 From <http://recaptcha.net/learnmore.html>:
53 reCAPTCHA improves the process of digitizing books by sending words that
55 cannot be read by computers to the Web in the form of CAPTCHAs for
56 humans to decipher. More specifically, each word that cannot be read
57 correctly by OCR is placed on an image and used as a CAPTCHA. This is
58 possible because most OCR programs alert you when a word cannot be read
59 correctly.
60 version 1 of Perl implementation is modelled on the PHP interface that
62 can be found here:
63 <http://recaptcha.net/plugins/php/>
65 To use reCAPTCHA you need to register your site here:
67 <https://www.google.com/recaptcha/admin/create>
69 Version 2 is a new and eaasy to solve captcha that is "easy for humans
71 to solve, but hard for 'bots' and other malicious software"
72
74 "new"
75 Create a new "Captcha::reCAPTCHA".
76 "get_options_setter( $options )"
78 You can optionally customize the look of the reCAPTCHA widget with
79 some JavaScript settings. "get_options_setter" returns a block of
80 Javascript wrapped in <script> .. </script> tags that will set the
81 options to be used by the widget.
82 $options is a reference to a hash that may contain the following
84 keys:
85 "theme"
87 Defines which theme to use for reCAPTCHA. Possible values are
88 'red', 'white' or 'blackglass'. The default is 'red'.
89 "tabindex"
91 Sets a tabindex for the reCAPTCHA text box. If other elements
92 in the form use a tabindex, this should be set so that
93 navigation is easier for the user. Default: 0.
94 "get_options_setter_div( $pubkey, $options )"
96 You can optionally customize the look of the reCAPTCHA widget with
97 some settings. "get_options_setter_div" returns a div element
98 wrapped in <div> .. </div> tags that will set the options to be
99 used by the widget.
100 $options is a reference to a hash that may contain the following
102 keys:
103 "data-theme"
105 Defines which theme to use for reCAPTCHA. Possible values are
106 'dark', 'light'. The default is 'light'.
107 "data-type"
109 Defines the type of captcha to server. Possible values are
110 'audio' or 'image'. Default is 'image'
111 "data-size"
113 Defines the size of the widget. Possible values are 'compact'
114 or 'normal'. Default is 'normal'
115 "data-tabindex"
117 Defines the tabindex of the widget and challenge. If other
118 elements in your page use tabindex, it should be set to make
119 user navigation easier. Default is 0
120 "data-callback"
122 Defines the name of your callback function to be executed when
123 the user submits a successful CAPTCHA response. The user's
124 response, g-recaptcha-response, will be the input for your
125 callback function.
126 "data-expired-callback"
128 Defines the name of your callback function to be executed when
129 the recaptcha response expires and the user needs to solve a
130 new CAPTCHA
131 "get_html_v2( $pubkey, \%options )"
133 Generates HTML to display the captcha using the new api pubkey is
134 public key for \%options types the same as get_options_setter
135 print $captcha->get_html_v2($pubkey, $options);
137 This uses ssl by default and does not display custom error messages
139 "get_html( $pubkey, $error, $use_ssl, \%options )"
141 Generates HTML to display the captcha using api version 1.
142 print $captcha->get_html( $PUB, $err );
144 $pubkey
146 Your reCAPTCHA public key, from the API Signup Page
147 $error
149 Optional. If set this should be either a string containing a
150 reCAPTCHA status code or a result hash as returned by
151 "check_answer".
152 $use_ssl
154 Optional. Should the SSL-based API be used? If you are
155 displaying a page to the user over SSL, be sure to set this to
156 true so an error dialog doesn't come up in the user's browser.
157 $options
159 Optional. A reference to a hash of options for the captcha. See
160 "get_options_setter" for more details.
161 Returns a string containing the HTML that should be used to display
163 the captcha.
164 "check_answer_v2"
166 After the user has filled out the HTML form, including their answer
167 for the CAPTCHA, use "check_answer" to check their answer when they
168 submit the form. The user's answer will be in field, g-recaptcha-
169 response. The reCAPTCHA library will make an HTTP request to the
170 reCAPTCHA server and verify the user's answer.
171 $privkey
173 Your reCAPTCHA private key, from the API Signup Page.
174 $remoteip
176 The user's IP address, in the format 192.168.0.1 (optional)
177 $response
179 The value of the form field recaptcha_response_field.
180 Returns a reference to a hash containing two fields: "is_valid" and
182 "error".
183 # If your site does not use SSL then
185 $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;
186 my $result = $c->check_answer_v2(
188 'your private key here', $response,
189 $ENV{'REMOTE_ADDR'}
190 );
191 my $result = $c->check_answer_v2(
193 'your private key here', $response,
194 $ENV{'REMOTE_ADDR'}
195 );
196 if ( $result->{is_valid} ) {
198 print "Yes!";
199 }
200 else {
201 # Error
202 $error = $result->{error};
203 }
204 See the /examples subdirectory for examples of how to call
206 "check_answer_v2".
207 Note: this method will make an HTTP request to Google to verify the
209 user input. If this request must be routed via a proxy in your
210 environment, use the standard environment variable to specify the
211 proxy address, e.g.:
212 $ENV{http_proxy} = 'http://myproxy:3128';
214 "check_answer"
216 After the user has filled out the HTML form, including their answer
217 for the CAPTCHA, use "check_answer" to check their answer when they
218 submit the form. The user's answer will be in two form fields,
219 recaptcha_challenge_field and recaptcha_response_field. The
220 reCAPTCHA library will make an HTTP request to the reCAPTCHA server
221 and verify the user's answer.
222 $privkey
224 Your reCAPTCHA private key, from the API Signup Page.
225 $remoteip
227 The user's IP address, in the format 192.168.0.1.
228 $challenge
230 The value of the form field recaptcha_challenge_field
231 $response
233 The value of the form field recaptcha_response_field.
234 Returns a reference to a hash containing two fields: "is_valid" and
236 "error".
237 my $result = $c->check_answer(
239 'your private key here', $ENV{'REMOTE_ADDR'},
240 $challenge, $response
241 );
242 if ( $result->{is_valid} ) {
244 print "Yes!";
245 }
246 else {
247 # Error
248 $error = $result->{error};
249 }
250 See the /examples subdirectory for examples of how to call
252 "check_answer_v1".
253 Note: this method will make an HTTP request to Google to verify the
255 user input. If this request must be routed via a proxy in your
256 environment, use the standard environment variable to specify the
257 proxy address, e.g.:
258 $ENV{http_proxy} = 'http://myproxy:3128';
260
262 Captcha::reCAPTCHA requires no configuration files or environment
263 variables.
264 To use reCAPTCHA sign up for a key pair here:
266 <https://www.google.com/recaptcha/admin/create>
268
270 LWP::UserAgent, HTML::Tiny
271
273 None reported .
274
276 Please see below link
277 https://rt.cpan.org/Public/Dist/Display.html?Name=Captcha-reCAPTCHA
279 Please report any bugs or feature requests to
281 "bug-captcha-recaptcha@rt.cpan.org", or through the web interface at
282 <http://rt.cpan.org>.
283
285 Mainainted by Sunny Patel "<sunnypatel4141@gmail.com>" Please report
286 all bugs to Sunny Patel
287 Version 0.95-0.97 was maintained by Fred Moyer
289 "<fred@redhotpenguin.com>"
290 Original Author Andy Armstrong "<andy@hexten.net>"
292
294 Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights
295 reserved.
296 This module is free software; you can redistribute it and/or modify it
298 under the same terms as Perl itself. See perlartistic.
299
301 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
302 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
303 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
304 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
305 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
306 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
307 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
308 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
309 NECESSARY SERVICING, REPAIR, OR CORRECTION.
310 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
312 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
313 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
314 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
315 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
316 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
317 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
318 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
319 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
320 DAMAGES.
321perl v5.34.0 2022-01-20 Captcha::reCAPTCHA(3)