Captch...HA::V3(3pm)

💖 Captcha::reCAPTCHA::V3 — the manual, but make it make sense 💖

okay bestie, buckle up, because this is Captcha::reCAPTCHA::V3 — a whole Perl implementation of reCAPTCHA API version v3, and it lives at Captch...HA::V3(3pm). yeah the header truncates it, tragic, but we move. ✨

---

🌸 NAME 🌸

Captcha::reCAPTCHA::V3 — a Perl implementation of reCAPTCHA API version v3. that's the whole vibe. it does the captcha thing. 💅

---

✨ SYNOPSIS ✨

Captcha::reCAPTCHA::V3 lets you plug Google reCAPTCHA v3 into your web apps. no cap.

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";
}

see how secret is the one that's Required and sitekey is just vibing as Optional? remember that. it comes back later. 🫶

---

🦋 DESCRIPTION 🦋

Captcha::reCAPTCHA::V3 is inspired from Captcha::reCAPTCHA::V2. it's giving glow-up, honestly.

and listen — this one is especially for Google reCAPTCHA v3, not for v2, because the APIs are so defferent. (their spelling, not mine, and honestly? iconic. we keep it. 🎀)

💜 Basic Usage 💜

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

when you're constructing the object, secret is the only thing you actually need. everything else is optional bestie.

also, fun fact: you can omit sitekey entirely (from version 0.0.4 onward). slay.

you do have to go get your keys before running anything though — from right here: <https://www.google.com/recaptcha/intro/v3.html>. yes, you gotta do the homework first, sorry. 🙈

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

per the official docs, query_name defaults to 'g-recaptcha-response', so if you went and changed it to something else, you have to set query_name to match. keep them in sync, bestie, or it's not gonna work. 💀

---

name([name])

you can get or set query_name after you've constructed the object — this is a version 0.0.4 and up thing.

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

and with overlording (they mean overloading, and yes i'm obsessed with this typo), you can grab query_name with just, like, this:

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

string context just knows. main character energy. 👑

---

verify( response )

this one requires just the one response key, straight from the Google reCAPTCHA API. that's it. that's the whole requirement.

DO NOT add remote address. there is no function for remote address within reCAPTCHA v3. seriously. don't. it's not a thing here. ✋

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

the default query_name is 'g-recaptcha-response', and it's stocked in the constructor. but now string-context provides you the query_name too, so we don't even have to care about it. convenient era. ✨

the response contains JSON, so it returns a decoded value from that 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 come with a score — it's telling you whether the request was by a bot or not. vibe check, basically.

so this method gives you evaluation by scores, from 0.0~1.0 (and it defaults to 0.5).

if the score came back lower than what you expected, the verifying fails, and it inserts 'too-low-score' into the top of the error-codes. dramatic, but fair. 💅

heads up: verify() requires just only one argument, because of compatibility for version 0.01. that's just how it is.

and in this method, the response pair SHOULD be set as a hash argument — and the score pair is optional.

---

🧚 Additional method for lazy (not sudgested) 🧚

(their words, not mine — "not sudgested". we're just the messengers. 🌈)

verify_or_die( response => response, [ score => score ] )

this is a wrapper of deny_by_score(). the differense? it dies imidiately when it fails to verify. no chill. no waiting. straight to the void. 😭

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

you can drop this somewhere inside your <body> tag.

in ordinal HTMLs, you'd set it up like this:

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

and boom — you might write less javascript lines. we love efficiency. 🔥

from 0.0.4 you can also set the debug flag in this method. it's just comment-out-ing the line below, but honestly? powerful.

//console.log(token);

---

💀 NOTES 💀

to test this module strictly, there's a necessary to run javascript in a test environment.

they 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. come contribute, bestie, the door is open. 🫶

---

🌈 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. free as in, go off. ✨

---

👑 AUTHOR 👑

worthmine <worthmine@gmail.com>

---

and that's the whole page, bestie!! this was rendered with perl v5.40.0 and dated 2024-12-14, and it was Captch...HA::V3(3pm) the whole time (yes the name is truncated, we're all coping). now go verify some captchas, you've got this. 💖🦋🌸