Expand documentation for `executeRecaptcha`

[ivan-kleshnin]

Hello @t49tran. Thank you for making this library! I think documentation can be improved by adding information on non-successful cases for executeRecaptcha.

Currently, README contains just this line:

const token = await this.props.googleReCaptchaProps.executeRecaptcha('homepage')

^ it's unclear what will happen if bot sends a request. Will it throw? Will it return null? Or empty string? Or an object with error data?

In my own experiments, sometimes it throws and sometimes an empty token is returned 🤔

Unfortunately, the official docs does not provide this information either: https://developers.google.com/recaptcha/docs/invisible

[t49tran]

Hi @ivan-kleshnin, sure, I will have a look into how to expand and handle it better.

In the mean time, if you have an idea on how it can be improved, feel free to create a PR.

[evanbiederstedt]

I also have struggled to best understand executeRecaptcha, and I'm not quite sure how to best improve the documentation in a PR. This could possibly be related to a conceptual misunderstanding related to reCAPTCHA v3 Enterprise...

For instance, what is the origin of the action string in executeRecaptcha()? The two examples in the README have actions "homepage" and "login_page", i.e.

import {
  GoogleReCaptchaProvider,
  useGoogleReCaptcha
} from 'react-google-recaptcha-v3';

const YourReCaptchaComponent  = () => {
  const { executeRecaptcha } = useGoogleReCaptcha();
  const token = executeRecaptcha("login_page");

  return (...)
}

ReactDom.render(
  <GoogleReCaptchaProvider reCaptchaKey="[Your recaptcha key]">
    <YourReCaptchaComponent />
  </GoogleReCaptchaProvider>,
  document.getElementById('app')
);

import {
  GoogleReCaptchaProvider,
  withGoogleReCaptcha
} from 'react-google-recaptcha-v3';

class ReCaptchaComponent extends React.Component {
  async componentDidMount() {
    const token = await this.props.googleReCaptchaProps.executeRecaptcha('homepage');
  }

  render() {
    ...
  }
}

Are these specific actions set and defined by the user? Or are these specific actions provided by reCAPTCHA? https://developers.google.com/recaptcha/docs/v3#actions

Apologies if this is obvious, and I'm happy to help out to try to document things better.

Best, Evan

[t49tran]

Hi @evanbiederstedt, the action can be anything you want. I am nowhere near Google Recaptcha team but my understanding about Recaptcha v3 is the process and the return value is heuristic / fuzzy. Ultimately Google will return a value between 0 and 1 (0 is likely to be a bot, while 1 is a human) and you decide for yourself whether the value is good enough.

The action is a part of it, Google use it to display an admin console:

I assume that Google will use the action as an input for their AI algorithm (maybe a neural network 😄 ).

[ivan-kleshnin]

To my understanding action is just a user defined string. It's used to mark different data channels or, in other words, to group them into separate buckets inside Google Admin. It does not affect captcha algorithm in any way and can be omitted. The only thing it affects is statistics and data representation.

[t49tran]

@ivan-kleshnin the second point is the document does mention: https://developers.google.com/recaptcha/docs/v3#actions adaptive risk analysis. I am not 100% sure if it's related to how ReCaptcha works, but it suggest that Google does use it for at least data analysing / mining purposes.

[ivan-kleshnin]

Ah, ok, good to know 👍

[evanbiederstedt]

Hi @t49tran @ivan-kleshnin

Thanks for the clarification. I think this makes a great deal of sense to me. The actions are user set strings, which will be displayed via the GCP console. I suppose these are partially used for the site administrators to control different settings based on the actions.

In terms of improving the README, although it's outside the scope of the library, it would be useful as a developer to see more hyperlinks of how others have parsed this token to get the score, and do things with the score (e.g. block IP addresses, set up v2 reCAPTCHA, etc.

[Enough7]

One more hint please include in the readme the difference between v3 and v2

[chema-mengibar]

Hi, I have a question about the "action" parameter. for some reason there is no data visible in the panel (as in the screenshot posted in another comment).

There is a way to debug what the package calls, also wich values sends in the "execute"? Thank you

[t49tran]

Hi @chema-mengibar, I am quite busy at the moment and might not be able to tend to this problem very soon, if you have time to investigate this yourself and share what you found I am happy to add it to ReadMe (you can make a PR for this).

Cheers