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
VerificationHandle
that 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 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 returnedVerificationResult
will 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 returnedVerificationResult
will 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
VerificationHandle
can be obtained through the returnedVerificationResult
, which you can use to callverifyAccount(String, VerificationHandle)
again. - API call failed: an
ApiException
will 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
VerificationResult
containing aStatus
indicating the status of the of the verification.