Provided by: libcaptcha-recaptcha-v3-perl_0.06-1_all bug

NAME
       Captcha::reCAPTCHA::V3 - A Perl implementation of reCAPTCHA API version v3


SYNOPSIS
       Captcha::reCAPTCHA::V3 provides you to integrate Google reCAPTCHA v3 for your web applications.

        use Captcha::reCAPTCHA::V3;
        my $rc = Captcha::reCAPTCHA::V3->new(
            sitekey => '__YOUR_SITEKEY__', # Optional
            secret  => '__YOUR_SECRET__',  # Required
        );

        ...

        my $content = $rc->verify($param{$rc});
        unless ( $content->{'success'} ) {
           # code for failing like below
           die 'fail to verify reCAPTCHA: ', @{ $content->{'error-codes'} }, "\n";
        }


DESCRIPTION
       Captcha::reCAPTCHA::V3 is inspired from Captcha::reCAPTCHA::V2

       This one is especially for Google reCAPTCHA v3, not for v2 because APIs are so defferent.

   Basic Usage
       new( secret => secret, [ sitekey => sitekey, query_name => query_name ] )

       Requires only secret when constructing.

       Now you can omit sitekey (from version 0.0.4).

       You have to get them before running from here <https://www.google.com/recaptcha/intro/v3.html>.

        my $rc = Captcha::reCAPTCHA::V3->new(
           sitekey => '__YOUR_SITEKEY__', # Optional
           secret  => '__YOUR_SECRET__',
           query_name => '__YOUR_QUERY_NAME__', # Optional
        );

       According to the official document, query_name defaults to 'g-recaptcha-response' so if you changed it
       another, you have to set query_name as same.

       name([name])

       You can get/set query_name after constuct the object from version 0.0.4

        my $query_name = $rc->name();  # defaults to 'g-recaptcha-response'
        $rc->name('captcha');          # the I<query_name> is now 'captcha'

       and with overlording, you can get query_name with just like below:

        my $query_name = "$rc";        # means same with $rc->name();

       verify( response )

       Requires just only response key being got from Google reCAPTCHA API.

       DO NOT add remote address. there is no function for remote address within reCAPTCHA v3.

        my $content = $rc->verify($param{$rc});

       The default query_name is 'g-recaptcha-response' and it is stocked in constructor.

       But now string-context provides you to get query_name so we don't have to care about it.

       The response contains JSON so it returns decoded value from JSON.

        unless ( $content->{'success'} ) {
           # code for failing like below
           die 'fail to verify reCAPTCHA: ', @{ $content->{'error-codes'} }, "\n";
        }

       deny_by_score( response => response, [ score => expected ] )

       reCAPTCHA v3 responses have score whether the request was by bot.

       So this method provides evaluation by scores that 0.0~1.0(defaults to 0.5)

       If the score was lower than what you expected, the verifying is fail with inserting 'too-low-score' into
       top of the error-codes.

       verify() requires just only one argument because of compatibility for version 0.01.

       In this method, the response pair SHOULD be set as a hash argument(score pair is optional).

   Additional method for lazy(not sudgested)
       verify_or_die( response => response, [ score => score ] )

       This method is a wrapper of deny_by_score(), the differense is dying imidiately when fail to verify.

       scripts( id => ID, [ debug => Boolen, action => action ] )

       You can insert this somewhere in your <body> tag.

       In ordinal HTMLs, you can set this like below:

        print <<"EOL", scripts( id => 'MailForm' );
        <form action="./" method="POST" id="MailForm">
           <input type="hidden" name="name" value="value">
           <button type="submit">send</button>
        </form>
        EOL

       Then you might write less javascript lines.

       From 0.0.4 you can set debug flag in this method.  this is just comment-out the below but powerful.

        //console.log(token);


NOTES
       To test this module strictly, there is a necessary to run javascript in test environment.

       I have not prepared it yet.

       So any PRs <https://github.com/worthmine/Captcha-reCAPTCHA-V3/pulls> and Issues
       <https://github.com/worthmine/Captcha-reCAPTCHA-V3/issues> are welcome.


SEE ALSO
       Captcha::reCAPTCHA::V2
       Google reCAPTCHA v3 <https://www.google.com/recaptcha/intro/v3.html>
       Google reCAPTCHA v3 API document <https://developers.google.com/recaptcha/docs/v3>


LICENSE
       Copyright (C) worthmine.

       This  library  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       itself.


AUTHOR
       worthmine <worthmine@gmail.com>

perl v5.40.0                                       2024-12-14                        Captcha::reCAPTCHA::V3(3pm)