RecaptchaClient
Page Summary
RecaptchaClient is the main entry point for interacting with the reCAPTCHA API.
You can use RecaptchaClient to challenge accounts for identity verification, close a RecaptchaHandle, execute an action to get a bot likelihood score, initialize a RecaptchaHandle, and verify an account using a PIN and verification handle.
The execute method returns a score indicating how likely an action was triggered by a real user, where scores near 0 suggest a bot and scores near 1 suggest a human.
The verifyAccount method verifies a PIN against a verification handle obtained through a challengeAccount call and returns a VerificationResult indicating the status of the verification.
The main entry point for interacting with the reCAPTCHA API.
Public Method Summary
| abstract Task<VerificationHandle> | challengeAccount(RecaptchaHandle recaptchaHandle,String challengeRequestToken) Sends a challenge to an account in order to verify the identity of the user. |
| abstract Task<Boolean> | |
| abstract Task<RecaptchaResultData> | execute(RecaptchaHandle handle,RecaptchaAction action) Returns a score indicating how likely the action was triggered by a real user. |
| abstract Task<RecaptchaHandle> | |
| abstract Task<VerificationResult> | verifyAccount(String pin, VerificationHandle verificationHandle) Verifies a PIN against a verification handle obtained through a challengeAccount(RecaptchaHandle, String) call. |
Public Methods
public abstract Task<VerificationHandle>challengeAccount(RecaptchaHandle recaptchaHandle,String challengeRequestToken)
Sends a challenge to an account in order to verify the identity of the user.
This method can be optionally called if you decide to perform a two factor authentication check on an account.
Parameters
| recaptchaHandle | RecaptchaHandle initialized through init(String). |
|---|---|
| challengeRequestToken | The challenge request token obtained through CreateAssessment(). |
Returns
- A
VerificationHandlethat can be used withverifyAccount(String, VerificationHandle)calls. A handle is usually valid for a specific time after creation. If an expired handle is returned, meaning the operation was aborted,getOperationAbortedToken()will return a token that can be used with the reCAPTCHA Enterprise API CreateAssessment() to get more details.
public abstract Task<Boolean>close(RecaptchaHandle handle)
Closes the initialized RecaptchaHandle.
Closes the handle if you will not be using it again to save resources.
Parameters
| handle | RecaptchaHandle initialized through init(String). |
|---|
Returns
- true if the handle got closed successfully for the first time, false if there wasn't anything to close (e.g., the handle was already previously closed).
public abstract Task<RecaptchaResultData>execute(RecaptchaHandle handle,RecaptchaAction action)
Returns a score indicating how likely the action was triggered by a real user. A score close to 0 indicates a likely bot, and a score close to 1 indicates a likely human.
This method should be called every time there is an action to be protected.
Parameters
| handle | RecaptchaHandle initialized through init(String). |
|---|---|
| action | User interaction that needs to be protected. |
public abstract Task<RecaptchaHandle>init(String siteKey)
Prepares and initializes a RecaptchaHandle.
Parameters
| siteKey | A site key registered for this app at//cloud.google.com/recaptcha-enterprise/docs/create-key |
|---|
public abstract Task<VerificationResult>verifyAccount(String pin,VerificationHandle verificationHandle)
Verifies a PIN against a verification handle obtained through a challengeAccount(RecaptchaHandle, String) call.
The method should be called to verify a PIN submitted by the user. The returnedVerificationResult will contain aStatus and either aVerificationHandle or a new reCAPTCHA token. The four possible cases are:
- API call succeeded and the verification status is
SUCCESS: the returnedVerificationResultwill contain a new reCAPTCHA token that can be used through the reCAPTCHA Enterprise API CreateAssessment() to verify that the user was indeed verified. - API call succeeded but the verification status is
RECAPTCHA_2FA_ABORTED: the returnedVerificationResultwill contain a new reCAPTCHA token that can be used through the reCAPTCHA Enterprise API CreateAssessment() to obtain more information on what went wrong. - API call succeeded but the verification failed with remaining attempts: the verification status will give more information about the failure and a new
VerificationHandlecan be obtained through the returnedVerificationResult, which you can use to callverifyAccount(String, VerificationHandle)again. - API call failed: an
ApiExceptionwill be thrown with a non-successStatus, which gives more information on what went wrong.
Parameters
| pin | The fixed-length numerical PIN entered by the user. If a PIN with unexpected length or non numerical characters is entered, a RECAPTCHA_2FA_INVALID_PIN error will be returned. |
|---|---|
| verificationHandle | A verification handle containing information required to preform the verification operation. |
Returns
- A
VerificationResultcontaining aStatusindicating the status of the of the verification.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-10-31 UTC.