---
name: "Captcha::reCAPTCHA::V3"
section: "3pm"
platform: "linux"
package: "libcaptcha-recaptcha-v3-perl"
version: "0.06-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Captcha::reCAPTCHA::V3"
---

# Captcha::reCAPTCHA::V3(3pm)

A Perl implementation of reCAPTCHA API version v3

## 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\>