Android SDK

Install the eu-captcha-android library to integrate EU CAPTCHA into your Android application.

Package	Version
`eu.eucaptcha.android:eu-captcha-android` · Source	1.0.0

Server-side verification is identical regardless of client platform — see Server-Side Verification. For other mobile integrations see iOS SDK and Flutter.

Requirements

Android 4.1 Jelly Bean (API level 16) or later
Written in Kotlin; compatible with both Kotlin and Java

Installation

Add mavenCentral() to your project-level repositories if it is not already present, then add the dependency to your module's build.gradle:

dependencies {
    implementation "eu.eucaptcha.android:eu-captcha-android:1.0.0"
}

Or in build.gradle.kts:

dependencies {
    implementation("eu.eucaptcha.android:eu-captcha-android:1.0.0")
}

Basic usage

Create an EuCaptchaSDK instance and use it to create a widget. Both are best held at the Activity level so they survive recomposition:

import eu.eucaptcha.android.sdk.*

class MainActivity : ComponentActivity() {
    private val sdk by lazy { EuCaptchaSDK(context = this) }
    private val widget by lazy { sdk.createWidget(sitekey = "EUCAPTCHA_SITE_KEY") }
}

2. Listen for state changes

Register a listener before the view is added to the layout. The listener fires on every widget state transition:

val captchaResponse = remember { mutableStateOf("") }
var submitEnabled by remember { mutableStateOf(false) }

widget.setOnStateChangeListener { event ->
    captchaResponse.value = event.response
    when (event.state) {
        EuCaptchaWidgetState.COMPLETED -> submitEnabled = true
        EuCaptchaWidgetState.EXPIRED   -> submitEnabled = false
        EuCaptchaWidgetState.ERROR     -> submitEnabled = true
    }
}

Use AndroidView in a Compose layout to render the widget:

AndroidView(
    factory = { _ -> widget.view },
    modifier = Modifier.fillMaxWidth().height(70.dp),
)

4. Submit the token

When the form is submitted, pass the captured token to your server for verification:

Button(
    onClick = { submitForm(captchaResponse.value) },
    enabled = submitEnabled,
) {
    Text("Submit")
}

After a failed submission, call widget.reset() so the user can solve a new challenge.

Customisation

EuCaptchaSDK.createWidget() accepts optional parameters:

Parameter	Type	Default	Description
`sitekey`	`String`	—	Your public sitekey (required)
`theme`	`String?`	`null`	`"light"`, `"dark"`, or `null` to follow the system UI mode
`language`	`String?`	`null`	BCP 47 language tag (e.g. `"en"`, `"de"`). Defaults to the device language.

Event listeners

EuCaptchaWidgetHandle exposes four event listeners. Each listener receives an event object that extends EuCaptchaWidgetEvent and exposes a response property holding the token string.

Method	Event class	Fired when
`setOnCompleteListener`	`EuCaptchaWidgetCompleteEvent`	The challenge finishes successfully. `event.response` holds the token.
`setOnExpireListener`	`EuCaptchaWidgetExpireEvent`	The token expires (60 minutes after completion).
`setOnErrorListener`	`EuCaptchaWidgetErrorEvent`	A network or server error occurs. `event.response` is `".ERROR"`.
`setOnStateChangeListener`	`EuCaptchaWidgetStateChangeEvent`	Any state transition occurs. `event.state` reflects the new state. Covers all of the above.

EuCaptchaWidgetState constants are reported via setOnStateChangeListener and the widget.state property:

Constant	Value	Description
`INIT`	`"init"`	Widget loaded; challenge not yet started
`CHECKING`	`"checking"`	Proof-of-work challenge in progress
`COMPLETED`	`"completed"`	Challenge finished — token is available in `event.response`
`EXPIRED`	`"expired"`	Token has expired; prompt the user to retry
`ERROR`	`"error"`	An error occurred during verification
`DESTROYED`	`"destroyed"`	Widget has been destroyed

API reference

`EuCaptchaSDK`

The main entry point. Create one instance per Activity or Application context.

EuCaptchaSDK(context: Context)

Method	Returns	Description
`createWidget(sitekey, theme?, language?)`	`EuCaptchaWidgetHandle`	Creates and returns a new widget handle.

`EuCaptchaWidgetHandle`

Returned by EuCaptchaSDK.createWidget().

Member	Type	Description
`view`	`android.view.View`	The view to embed in your layout via `AndroidView`.
`state`	`String`	The current widget state (see Widget states).
`response`	`String`	The current token, or a sentinel value if the challenge is not yet complete.
`setOnCompleteListener(listener)`	—	Register a listener called when the challenge completes.
`setOnExpireListener(listener)`	—	Register a listener called when the token expires.
`setOnErrorListener(listener)`	—	Register a listener called on error.
`setOnStateChangeListener(listener)`	—	Register a listener called on every state change.
`reset()`	—	Reload the widget so a new challenge can be solved. Call after a rejected submission.
`destroy()`	—	Release WebView resources. Call from `onDestroy()` when the widget is no longer needed.

Server-side verification

After your server receives the form submission, verify the token by passing event.response as client_token to the Verification API.

For ready-made server libraries, see Server-Side Verification.