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.98
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               my $result = $c->check_answer_v2(
185                   'your private key here', $response,
186                   $ENV{'REMOTE_ADDR'}
187               );
188
189               my $result = $c->check_answer_v2(
190                   'your private key here', $response,
191                   $ENV{'REMOTE_ADDR'}
192               );
193
194               if ( $result->{is_valid} ) {
195                   print "Yes!";
196               }
197               else {
198                   # Error
199                   $error = $result->{error};
200               }
201
202           See the /examples subdirectory for examples of how to call
203           "check_answer_v2".
204
205           Note: this method will make an HTTP request to Google to verify the
206           user input.  If this request must be routed via a proxy in your
207           environment, use the standard environment variable to specify the
208           proxy address, e.g.:
209
210               $ENV{http_proxy} = 'http://myproxy:3128';
211
212       "check_answer"
213           After the user has filled out the HTML form, including their answer
214           for the CAPTCHA, use "check_answer" to check their answer when they
215           submit the form. The user's answer will be in two form fields,
216           recaptcha_challenge_field and recaptcha_response_field. The
217           reCAPTCHA library will make an HTTP request to the reCAPTCHA server
218           and verify the user's answer.
219
220           $privkey
221               Your reCAPTCHA private key, from the API Signup Page.
222
223           $remoteip
224               The user's IP address, in the format 192.168.0.1.
225
226           $challenge
227               The value of the form field recaptcha_challenge_field
228
229           $response
230               The value of the form field recaptcha_response_field.
231
232           Returns a reference to a hash containing two fields: "is_valid" and
233           "error".
234
235               my $result = $c->check_answer(
236                   'your private key here', $ENV{'REMOTE_ADDR'},
237                   $challenge, $response
238               );
239
240               if ( $result->{is_valid} ) {
241                   print "Yes!";
242               }
243               else {
244                   # Error
245                   $error = $result->{error};
246               }
247
248           See the /examples subdirectory for examples of how to call
249           "check_answer_v1".
250
251           Note: this method will make an HTTP request to Google to verify the
252           user input.  If this request must be routed via a proxy in your
253           environment, use the standard environment variable to specify the
254           proxy address, e.g.:
255
256               $ENV{http_proxy} = 'http://myproxy:3128';
257

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

267       LWP::UserAgent, HTML::Tiny
268

INCOMPATIBILITIES

270       None reported .
271

BUGS AND LIMITATIONS

273       Please see below link
274
275       https://rt.cpan.org/Public/Dist/Display.html?Name=Captcha-reCAPTCHA
276
277       Please report any bugs or feature requests to
278       "bug-captcha-recaptcha@rt.cpan.org", or through the web interface at
279       <http://rt.cpan.org>.
280

AUTHOR

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

DISCLAIMER OF WARRANTY

298       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
299       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
300       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
301       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
302       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
303       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
304       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
305       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
306       NECESSARY SERVICING, REPAIR, OR CORRECTION.
307
308       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
309       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
310       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
311       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
312       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
313       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
314       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
315       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
316       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
317       DAMAGES.
318
319
320
321perl v5.28.1                      2019-02-02             Captcha::reCAPTCHA(3)
Impressum