ReCaptchaEnterpriseCallback

public class ReCaptchaEnterpriseCallback : AbstractCallback, @unchecked Sendable

A callback implementation for executing Google reCAPTCHA Enterprise verification.

This callback is used within the Ping Identity journey framework to perform bot detection and fraud prevention using Google’s reCAPTCHA Enterprise service. It extends AbstractCallback for modern Swift callback handling and provides a streamlined interface for reCAPTCHA execution.

Usage in Journey Flow

  1. Server sends callback with reCAPTCHA site key and input field configuration
  2. Callback receives configuration via initValue calls
  3. Client calls verify() to obtain reCAPTCHA token
  4. Token and action are submitted back to server for verification

Security Considerations

  • Never expose site keys in client code
  • Handle errors gracefully without exposing implementation details
  • Use appropriate actions for different user flows

Configuration Properties

  • The reCAPTCHA Enterprise site key provided by the server. This key identifies your site to Google’s reCAPTCHA service.

    Declaration

    Swift

    private(set) public var recaptchaSiteKey: String { get }

  • The name of the input field for the reCAPTCHA token. This is determined from the server configuration.

    Declaration

    Swift

    private(set) public var tokenKey: String { get }

  • The name of the input field for the action. This is determined from the server configuration.

    Declaration

    Swift

    private(set) public var actionKey: String { get }

  • The name of the input field for client errors. This is determined from the server configuration.

    Declaration

    Swift

    private(set) public var clientErrorKey: String { get }

  • The name of the input field for additional payload. This is determined from the server configuration.

    Declaration

    Swift

    private(set) public var payloadKey: String { get }

Initialization

  • initialize(with:) Asynchronous

    Initializes a new instance of ReCaptchaEnterpriseCallback with the provided JSON.

    Declaration

    Swift

    public override func initialize(with json: [String : Any]) async -> any Callback

  • Initializes callback properties based on server-provided configuration.

    This method is called automatically during callback initialization to set up the callback based on the server’s requirements for reCAPTCHA verification.

    Supported Properties

    • recaptchaSiteKey: String containing the reCAPTCHA site key
    • Input field names are detected from input keys containing specific keywords

    Declaration

    Swift

    public override func initValue(name: String, value: Any)

    Parameters

    name

    The name of the property being initialized
    value

    The value containing the property configuration

Execution Methods

  • verify(configBlock:) Asynchronous

    Executes reCAPTCHA Enterprise verification and submits the result to the server.

    This method orchestrates the complete reCAPTCHA verification process, allowing for custom configuration of the execution parameters.

    Execution Process

    1. Creates ReCaptchaEnterpriseConfig with default settings
    2. Applies custom configuration via configBlock
    3. Fetches reCAPTCHA client with site key
    4. Executes reCAPTCHA action with specified timeout
    5. Submits token and action to server

    Configuration Example

    let result = await callback.verify { config in
    config.action = "signup"
    config.timeout = 20000
    config.provider = CustomRecaptchaProvider()
}

    Error Handling

    • Automatically submits successful results to server
    • Client errors are captured and submitted to server

    Declaration

    Swift

    public func verify(
    configBlock: @escaping @Sendable (ReCaptchaEnterpriseConfig) -> Void = {_ in }
) async -> Result<String, Error>

    Parameters

    configBlock

    Configuration block for customizing reCAPTCHA execution

    Return Value

    Result containing the reCAPTCHA token or an error

Input Setting Methods

  • Sets the reCAPTCHA token value in the callback response. - Parameter value: String value of the reCAPTCHA token

    Declaration

    Swift

    public func setToken(_ value: String)

  • Sets the client error value in the callback response.

    Declaration

    Swift

    public func setClientError(_ value: String)

    Parameters

    value

    String value of the error message

  • Sets additional payload value for the reCAPTCHA in callback response.

    Declaration

    Swift

    public func setPayload(_ value: [String : Any]? = nil)

    Parameters

    value

    Dictionary value of additional data

  • Returns the payload for the callback submission.

    Declaration

    Swift

    public override func payload() -> [String : Any]

    Return Value

    JSON dictionary for server submission