1Captcha::reCAPTCHA(3) User Contributed Perl DocumentationCaptcha::reCAPTCHA(3)
2
3
4

NAME

6       Captcha::reCAPTCHA - A Perl implementation of the reCAPTCHA API
7

VERSION

9       This document describes Captcha::reCAPTCHA version 0.99
10

NOTICE

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

SYNOPSIS

16       Note this release contains methods that use
17
18           use Captcha::reCAPTCHA;
19
20           my $c = Captcha::reCAPTCHA->new;
21
22           # Output form New Version
23           print $c->get_html_v2( 'your public key here' );
24
25           # Version 1 (not recommended)
26           print $c->get_html( 'your public key here' );
27
28           # Verify submission
29           my $result $c->check_answer_v2($private_key, $response, $ENV{REMOTE_ADDR});
30
31           # Verify submission (Old Version)
32           my $result = $c->check_answer(
33               'your private key here', $ENV{'REMOTE_ADDR'},
34               $challenge, $response
35           );
36
37           if ( $result->{is_valid} ) {
38               print "Yes!";
39           }
40           else {
41               # Error
42               $error = $result->{error};
43           }
44
45       For complete examples see the /examples subdirectory
46

DESCRIPTION

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
52       From <http://recaptcha.net/learnmore.html>:
53
54           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
61       version 1 of Perl implementation is modelled on the PHP interface that
62       can be found here:
63
64       <http://recaptcha.net/plugins/php/>
65
66       To use reCAPTCHA you need to register your site here:
67
68       <https://www.google.com/recaptcha/admin/create>
69
70       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

INTERFACE

74       "new"
75           Create a new "Captcha::reCAPTCHA".
76
77       "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
83           $options is a reference to a hash that may contain the following
84           keys:
85
86           "theme"
87               Defines which theme to use for reCAPTCHA. Possible values are
88               'red', 'white' or 'blackglass'. The default is 'red'.
89
90           "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
95       "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
101           $options is a reference to a hash that may contain the following
102           keys:
103
104           "data-theme"
105               Defines which theme to use for reCAPTCHA. Possible values are
106               'dark', 'light'. The default is 'light'.
107
108           "data-type"
109               Defines the type of captcha to server. Possible values are
110               'audio' or 'image'.  Default is 'image'
111
112           "data-size"
113               Defines the size of the widget. Possible values are 'compact'
114               or 'normal'.  Default is 'normal'
115
116           "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
121           "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
127           "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
132       "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
136             print $captcha->get_html_v2($pubkey, $options);
137
138           This uses ssl by default and does not display custom error messages
139
140       "get_html( $pubkey, $error, $use_ssl, \%options )"
141           Generates HTML to display the captcha using api version 1.
142
143               print $captcha->get_html( $PUB, $err );
144
145           $pubkey
146               Your reCAPTCHA public key, from the API Signup Page
147
148           $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
153           $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
158           $options
159               Optional. A reference to a hash of options for the captcha. See
160               "get_options_setter" for more details.
161
162           Returns a string containing the HTML that should be used to display
163           the captcha.
164
165       "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
172           $privkey
173               Your reCAPTCHA private key, from the API Signup Page.
174
175           $remoteip
176               The user's IP address, in the format 192.168.0.1 (optional)
177
178           $response
179               The value of the form field recaptcha_response_field.
180
181           Returns a reference to a hash containing two fields: "is_valid" and
182           "error".
183
184                   # If your site does not use SSL then
185                   $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;
186
187               my $result = $c->check_answer_v2(
188                   'your private key here', $response,
189                   $ENV{'REMOTE_ADDR'}
190               );
191
192               my $result = $c->check_answer_v2(
193                   'your private key here', $response,
194                   $ENV{'REMOTE_ADDR'}
195               );
196
197               if ( $result->{is_valid} ) {
198                   print "Yes!";
199               }
200               else {
201                   # Error
202                   $error = $result->{error};
203               }
204
205           See the /examples subdirectory for examples of how to call
206           "check_answer_v2".
207
208           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
213               $ENV{http_proxy} = 'http://myproxy:3128';
214
215       "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
223           $privkey
224               Your reCAPTCHA private key, from the API Signup Page.
225
226           $remoteip
227               The user's IP address, in the format 192.168.0.1.
228
229           $challenge
230               The value of the form field recaptcha_challenge_field
231
232           $response
233               The value of the form field recaptcha_response_field.
234
235           Returns a reference to a hash containing two fields: "is_valid" and
236           "error".
237
238               my $result = $c->check_answer(
239                   'your private key here', $ENV{'REMOTE_ADDR'},
240                   $challenge, $response
241               );
242
243               if ( $result->{is_valid} ) {
244                   print "Yes!";
245               }
246               else {
247                   # Error
248                   $error = $result->{error};
249               }
250
251           See the /examples subdirectory for examples of how to call
252           "check_answer_v1".
253
254           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
259               $ENV{http_proxy} = 'http://myproxy:3128';
260

CONFIGURATION AND ENVIRONMENT

262       Captcha::reCAPTCHA requires no configuration files or environment
263       variables.
264
265       To use reCAPTCHA sign up for a key pair here:
266
267       <https://www.google.com/recaptcha/admin/create>
268

DEPENDENCIES

270       LWP::UserAgent, HTML::Tiny
271

INCOMPATIBILITIES

273       None reported .
274

BUGS AND LIMITATIONS

276       Please see below link
277
278       https://rt.cpan.org/Public/Dist/Display.html?Name=Captcha-reCAPTCHA
279
280       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

AUTHOR

285       Mainainted by Sunny Patel "<sunnypatel4141@gmail.com>" Please report
286       all bugs to Sunny Patel
287
288       Version 0.95-0.97 was maintained by Fred Moyer
289       "<fred@redhotpenguin.com>"
290
291       Original Author Andy Armstrong  "<andy@hexten.net>"
292
294       Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights
295       reserved.
296
297       This module is free software; you can redistribute it and/or modify it
298       under the same terms as Perl itself. See perlartistic.
299

DISCLAIMER OF WARRANTY

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
311       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.
321
322
323
324perl v5.36.0                      2022-07-22             Captcha::reCAPTCHA(3)
Impressum