Orchestration SDKs

Integrating reCAPTCHA Enterprise into an Android app

PingOne Advanced Identity Cloud PingAM Android

To add support for reCAPTCHA Enterprise to your Android apps, complete the following tasks.

Importing dependencies

Add the following to your build.gradle configuration file:

dependencies {
    implementation("com.pingidentity.sdks:recaptcha-enterprise:2.0.0")
}

Handling the callback with the SDK

Use code similar to the following to handle the ReCaptchaEnterpriseCallback in your client-side code using the Orchestration SDKs:

Handling ReCaptchaEnterpriseCallback on Android
val node = journey.start("login")

node.callbacks.forEach { callback ->
    when (callback) {
        is ReCaptchaEnterpriseCallback -> {
            val result = callback.verify()
            result.onSuccess { token ->
                // Verification successful, proceed with the flow
                println("ReCaptcha token: $token")
            }.onFailure { error ->
                // Handle verification failure
                println("Verification failed: ${error.message}")
            }
        }
        // Handle other callbacks
    }
}

// Continue the journey
val next = node.next()

Configuring the verification

You can pass a number of options into the call to verify() to customize its operation:

Configuring the call to verify() on Android
callback.verify {
    // Different action types
    recaptchaAction = RecaptchaAction.SIGNUP
    // or custom action
    recaptchaAction = RecaptchaAction.custom("PASSWORD_RESET")

    // Longer timeout for slower networks
    timeoutInMills = 15000L
}

The available properties for configuring the verify() call are as follows:

Property Default Description

recaptchaAction (RecaptchaAction)

RecaptchaAction.LOGIN

The type of action you want to verify.

Specify either of the built-in values:

RecaptchaAction.LOGIN

For login journeys

RecaptchaAction.SIGNUP

For registration journeys

Or you can specify your own action using the custom method:

RecaptchaAction.custom("PASSWORD_RESET")
RecaptchaAction.custom("PAYMENT")
RecaptchaAction.custom("ADD_TO_CART")

timeoutInMills (Long)

10000L

How long to wait, in milliseconds, for a verification to complete.

Use longer timeouts for slow networks or critical operations.

customPayload (JsonObject?)

null

Add relevant metadata to help with risk assessment and debugging.

Learn more in Customizing the assessment payload.

logger (Logger)

Logger.WARN

What level of logging the module should output.

Choose from the following options:

Logger.DEBUG

Detailed debugging messages, for use during development.

Logger.WARN

Only logs warnings and errors.

Logger.INFO

Logs info-level messages.

Logger.NONE

Disables logging.

Customizing the assessment payload

You can add additional data to customize the payload that the server sends to the Google reCAPTCHA Enterprise for assessment.

Add data to the payload to leverage additional functionality provided by reCAPTCHA Enterprise.

The JSON format the payload expects is as follows:

{
  "token": string,
  "siteKey": string,
  "userAgent": string,
  "userIpAddress": string,
  "expectedAction": string,
  "hashedAccountId": string,
  "express": boolean,
  "requestedUri": string,
  "wafTokenAssessment": boolean,
  "ja3": string,
  "headers": [
    string
  ],
  "firewallPolicyEvaluation": boolean,
  "transactionData": {
    object (TransactionData)
  },
  "userInfo": {
    object (UserInfo)
  },
  "fraudPrevention": enum (FraudPrevention)
}

By default, the SDK or the node itself populates the following fields:

  • token

  • siteKey

  • userAgent

  • userIpAddress

  • expectedAction

You can however also override these values if it suits your use case.

You can add custom payload data as part of an authentication journey that includes the reCAPTCHA Enterprise node. Custom data in the journey overrides any custom data added by the client.

To learn more about the payload, refer to Project Assessments - Event in the Google Developer documentation.

To add custom data for an assessment, set the customPayload property in the verify configuration block:

Customizing reCAPTCHA payload on Android
callback.verify {
    // Add custom payload for risk assessment
    customPayload = buildJsonObject {
        put("firewallPolicyEvaluation", true)
        put("transactionData", buildJsonObject {
            put("transactionId", "TXN-12345")
            put("paymentMethod", "CREDIT_CARD")
            put("cardBin", "123456")
            put("cardLastFour", "1234")
            put("currencyCode", "USD")
            put("value", 99.99)
        })
        put("userInfo", buildJsonObject {
            put("accountId", "user-abc123")
            put("creationMs", "1609459200000")
        })
    }
}

Returning custom error codes

You can return a custom error to the node if required for your business logic:

Returning custom reCAPTCHA client errors on Android
val result = callback.verify {

  // Optional custom client error code
  customError = { exception ->
      "custom_client_error ${exception.message?.uppercase()}"
  }
}