How to Integrate hCaptcha with an Android App

How do you integrate hCaptcha with an Android app?#

Add the official hCaptcha Android SDK from JitPack, configure it with your public sitekey, and trigger verification from the protected action. Both the Android Views SDK and Jetpack Compose component return a token. Send that token to your backend and accept the request only after hCaptcha Siteverify returns success: true.

Keep Android verification less disruptive#

• Keep users focused on the app. hCaptcha Pro's 99.9% Passive mode minimizes visual challenges during protected actions in your Views or Compose interface.
• Reserve stronger checks for suspicious activity. Pro adapts verification to risk, so routine app use involves fewer interruptions while suspicious attempts receive more scrutiny. Keep the SDK's visual challenge fallback available; headless mode requires Enterprise.

New Pro sitekeys use 99.9% Passive by default. For an existing sitekey upgraded to Pro, select that mode under Behavior in the hCaptcha dashboard.

Before you start#

These instructions were last validated on September 22, 2026 with Android SDK 5.0.1.

You need:

• An Android app with a backend endpoint for its protected action.
• A FragmentActivity for the default visual dialog, or an appropriate embedded container.
• An hCaptcha account with a sitekey and matching secret.
• A secure backend secret store and outbound HTTPS access to hCaptcha.

Review the official Android SDK repository and hCaptcha mobile SDK and integration catalog entries. The integrations-list repository records the broader catalog.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected Android app actions, or use existing compatible hCaptcha credentials.
2. Create a sitekey for the Android application.
3. Put the public sitekey in app configuration or an HCaptchaConfig object.
4. Store the matching secret only in protected backend configuration.

The sitekey can ship with the application. The secret cannot. Never place it in Kotlin or Java code, AndroidManifest.xml, resources, BuildConfig, or the application package.

Install the SDK from JitPack#

Add JitPack to dependency repositories, then choose the module that matches the UI:

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.hCaptcha.hcaptcha-android-sdk:sdk:5.0.1")
    // For Jetpack Compose instead:
    // implementation("com.github.hCaptcha.hcaptcha-android-sdk:compose-sdk:5.0.1")
}

Version 5 uses these module-specific coordinates. Older instructions that use com.github.hcaptcha:hcaptcha-android-sdk apply only before version 5.

Add hCaptcha to an Android Views flow#

Create one client for the Activity, register its listeners, and pass a configured sitekey:

private lateinit var hcaptcha: HCaptcha

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val config = HCaptchaConfig.builder()
        .siteKey(BuildConfig.HCAPTCHA_SITEKEY)
        .size(HCaptchaSize.INVISIBLE)
        .build()

    hcaptcha = HCaptcha.getClient(this)
        .addOnSuccessListener { response ->
            sendRequestToBackend(response.tokenResult)
            response.markUsed()
        }
        .addOnFailureListener { error ->
            showVerificationError(error)
        }

    hcaptcha.setup(config)
}

private fun submit() {
    hcaptcha.verifyWithHCaptcha()
}

override fun onDestroy() {
    hcaptcha.removeAllListeners()
    hcaptcha.destroy()
    super.onDestroy()
}

markUsed() cancels the SDK's later token-timeout callback after the application consumes the token. Listeners persist across verifications, so remove them during teardown. Reuse the initialized client for repeated verifications on the same screen; the SDK caches its verifier for that purpose. Call reset() when you intentionally need to release and recreate the verifier, and call destroy() during final lifecycle cleanup.

The default dialog mode requires FragmentActivity. Embedded mode can render inside a supplied container on a regular Activity. Headless mode requires an Enterprise Passive sitekey.

Add hCaptcha with Jetpack Compose#

The Compose module exposes HCaptchaCompose. Its result handler reports successful tokens, failures, and lifecycle events.

val config = HCaptchaConfig.builder()
    .siteKey(BuildConfig.HCAPTCHA_SITEKEY)
    .renderMode(HCaptchaRenderMode.DIALOG)
    .build()

HCaptchaCompose(config = config) { result ->
    when (result) {
        is HCaptchaResponse.Success -> sendRequestToBackend(result.token)
        is HCaptchaResponse.Failure -> showVerificationError(result.error)
        is HCaptchaResponse.Event -> recordCaptchaEvent(result.event)
    }
}

Test recomposition, navigation, Activity recreation, and listener cleanup in the real application. The Compose module requires API 21 or later.

Verify the token on your backend#

The backend must reject missing tokens, send a URL-encoded POST to https://api.hcaptcha.com/siteverify, and include the server-held secret plus the mobile token as response. Include the expected sitekey so a token issued for another sitekey cannot satisfy the endpoint. The remoteip parameter is optional. We recommend sending it for improved verification accuracy and Enterprise risk scores when the backend derives the visitor's IP address from a reviewed, trusted proxy configuration; otherwise omit it. Continue only when the JSON response contains success: true.

Follow the server-side verification documentation. The SDK success callback does not authorize the protected action.

Test the complete Android flow#

1. Confirm successful tokens work once and reused tokens fail.
2. Test missing tokens, expiration, cancellation, offline mode, and slow networks.
3. Exercise rotation, backgrounding, navigation, and repeated verification.
4. Confirm listeners and WebView resources are released during teardown.
5. Test the minimum supported API for the selected module and current target SDK on physical devices.
6. For camera challenges, request CAMERA permission at runtime and use API 21 or later.

Troubleshoot common Android problems#

Gradle cannot resolve the dependency

Confirm JitPack is in dependency repositories and use the version 5 module coordinate. Test dependency resolution with the application's toolchain.

A visual challenge throws a FragmentActivity error

Use FragmentActivity for dialog mode. A regular Activity works with an embedded container, or with headless mode and an Enterprise Passive sitekey.

Callbacks fire more than once

Listeners persist across verifications. Avoid registering duplicates, remove listeners during teardown, and account for configured retry behavior.

A token-timeout error appears after submission

Call markUsed() after your app has consumed the successful token. The SDK's default expiration timer is 120 seconds.

Frequently asked questions#

Does the guide cover Android Views and Jetpack Compose?

Yes. Use the sdk module for Views or compose-sdk for Compose. Their minimum API levels differ: 16 for core and 21 for Compose.

Is the hCaptcha Android SDK official?

Yes. We maintain the repository and link it from our mobile SDK and integration catalogs.

Does the Android SDK verify tokens on the backend?

No. Your backend must send every token and the private secret to Siteverify before accepting the request.

Can the hCaptcha secret be stored in the Android app?

No. Application packages can be inspected. Keep the secret on the backend and expose only the sitekey to the app.

Which Android SDK versions receive security support?

The repository security policy lists major versions 5 and 4 as supported. Versions earlier than 4 are unsupported.