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
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
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 returned VerificationResult
will contain a Status
and either a VerificationHandle
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.
