https://github.com/friendlycaptcha/friendly-captcha-android
Android SDK for Friendly Captcha
https://github.com/friendlycaptcha/friendly-captcha-android
android captcha friendly-captcha library sdk
Last synced: 3 months ago
JSON representation
Android SDK for Friendly Captcha
- Host: GitHub
- URL: https://github.com/friendlycaptcha/friendly-captcha-android
- Owner: FriendlyCaptcha
- Created: 2024-10-24T11:20:28.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-12-19T11:25:58.000Z (7 months ago)
- Last Synced: 2025-03-28T06:02:54.905Z (3 months ago)
- Topics: android, captcha, friendly-captcha, library, sdk
- Language: Kotlin
- Homepage: https://developer.friendlycaptcha.com
- Size: 263 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Friendly Captcha Android SDK
[
](https://central.sonatype.com/artifact/com.friendlycaptcha.android/friendly-captcha-android) [](https://javadoc.io/doc/com.friendlycaptcha.android/friendly-captcha-android)
The Friendly Captcha Android SDK allows you to easily integrate [Friendly Captcha](https://friendlycaptcha.com) into your Android applications.
> This SDK is for **Friendly Captcha v2**.
## Installation
Add the following to your `build.gradle` file:
```gradle
repositories {
mavenCentral()
}
dependencies {
implementation "com.friendlycaptcha:friendly-captcha-android:1.0.1"
// Or for `build.gradle.kts`
// implementation("com.friendlycaptcha:friendly-captcha-android:1.0.1")
}
```
You can find the latest version number on the [Releases](https://github.com/FriendlyCaptcha/friendly-capthca-android/releases) page.
## Documentation
See the documentation for the full API reference [here](https://javadoc.io/doc/com.friendlycaptcha.android/friendly-captcha-android).
## Supported Platforms
The SDK supports **Android 4.1 Jelly Bean** (API level 16, released June 2012) and above.
This SDK is written in Kotlin and is compatible with both Kotlin and Java.
## Usage
### Kotlin (Compose)
Import the Friendly Captcha SDK
```kotlin
import com.friendlycaptcha.android.sdk.*;
```
Then create an instance of `FriendlyCaptchaSDK`, and create a widget with your site key:
```kotlin
const val FRIENDLY_CAPTCHA_SITEKEY = "YOUR_SITEKEY"
class MainActivity : ComponentActivity() {
private val sdk by lazy {
FriendlyCaptchaSDK(context = this, apiEndpoint = "global")
}
private val widget by lazy {
sdk.createWidget(sitekey = FRIENDLY_CAPTCHA_SITEKEY)
}
// ...
}
```
Then in the UI you are going to use the widget, add the following:
```kotlin
val captchaResponse = remember { mutableStateOf("") }
var buttonEnabled by remember { mutableStateOf(false) }
widget.setOnStateChangeListener { event ->
captchaResponse.value = event.response
when (event.state) {
"completed" -> buttonEnabled = true
// The user will be able to restart the widget by clicking it.
"expired" -> buttonEnabled = false
// We enable the button on errors too, if Friendly Captcha is misbehaving (i.e. it's offline),
// the user can still submit the form (albeit without a valid captcha response).
"error" -> buttonEnabled = true
"reset" -> buttonEnabled = false
}
}
// The rest of your UI
AndroidView( // This is a Compose view that wraps the Friendly Captcha widget
factory = { _ ->
widget.view
},
)
Button(
onClick = {
// Do something with the captcha response - usually you would send it to your backend
// for verification, along with the rest of the form data.
Log.d("MainActivity", "Captcha response: ${captchaResponse.value}")
// Reset the widget after submitting the form, the captcha response is only valid once.
widget.reset()
},
enabled = buttonEnabled
) {
Text("Submit")
}
```
For a full end-to-end example see the [example app](./example-app/).
### Kotlin (AndroidView)
If you are not using Jetpack Compose, you can use the `AndroidView` API to embed the widget in your existing Android views. An example for that
can be found in the [debugapp](./sdk/debugapp/src/main/java/com/friendlycaptcha/android/debugapp/MainActivity.kt).
### Kotlin Example App
The example app demonstrates how to use the Friendly Captcha SDK in a simple Android app.
To run the example app, clone this repository and open the [`example-app`](./example-app) directory in Android Studio.
## License
This is free software; you can redistribute it and/or modify it under the terms of the [Mozilla Public License Version 2.0](./sdk/LICENSE).
All examples are released under the [MIT license](./example-app/LICENSE).