RecaptchaClient

public interface RecaptchaClient

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>	close(RecaptchaHandle handle) Closes the initialized RecaptchaHandle.
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>	init(String siteKey) Prepares and initializes a 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 with verifyAccount(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 returned VerificationResult 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 returned VerificationResult 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 returned VerificationResult, which you can use to call verifyAccount(String, VerificationHandle) again.
• API call failed: an ApiException will be thrown with a non-success Status, 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 a Status indicating the status of the of the verification.