This page explains how to integrate reCAPTCHA in your Android app.
The SDK uses reflection and dynamic code to allow modification and refinement of the detection system in the existing deployed applications/SDKs. The set of classes that are available in the system are restricted to a controlled list to avoid interference with the application.
Before you begin
-
Create a reCAPTCHA Key for the Android app platform.
Alternatively, you can copy the ID of an existing reCAPTCHA key for Android by performing one of the following steps:
-
To copy the ID of an existing key from the Google Cloud console, do the following:
-
Go to the reCAPTCHApage.
- In the reCAPTCHA keys list, hold the pointer over the key you want to copy, and then click .
-
- To copy the ID of an existing key using the REST API, use the projects.keys.list method.
- To copy the ID of an existing key using the gcloud CLI, use the gcloud recaptcha keys list command.
-
Prepare your Android environment
Native Android
-
Prepare your development environment by downloading and installing the latest version of Android Studio .
-
Ensure that you have an app with the minimum Android SDK value set to API 23: Android 6.0 (Marshmallow).
-
If you are creating a new mobile app, create a test application by starting a new Android Studio project:
- Select Empty Activity. If you want to use Jetpack Compose on your app choose Empty Compose Activity.
- Set the language to kotlin.
- Set the minimum SDK value to API 23: Android 6.0 (Marshmallow).
-
Ensure that Google's Maven repository
google()is in the list of repositories in the project-levelbuild.gradlefile as shown in the following snippet:allprojects { repositories { google () } }For more information, see Google's Maven repository .
-
To add the reCAPTCHA API dependency, add the following build rule to the
dependenciessection of your app-levelbuild.gradlefile.implementation ' com . google . android . recaptcha : recaptcha : 18.8.0 - beta03 'For more information about adding dependencies in Android apps, see Add build dependencies .
-
Add internet permission between the first
<manifest>tag and the first<application>tag in your application's manifest (for example,AndroidManifest.xml). This permission is required because the reCAPTCHA API involves network operations.<manifest ...> <uses-permission android:name="android.permission.INTERNET" /> <application ...> ... </application> </manifest> -
If you want to use
AndroidXlibraries in your new project, compile the SDK to Android 9.0 or higher and add the following code snippet to yourgradle.properties.android.useAndroidX=true android.enableJetifier=trueFor more information, see Migrating to AndroidX .
Flutter
For detailed instructions about using reCAPTCHA through Flutter, see the Flutter documentation .
React Native
For detailed instructions about using reCAPTCHA through React Native, see the React Native documentation .
Integrate reCAPTCHA with your Android app
-
Instantiate a client by using the reCAPTCHA key (KEY_ID) that you created for your Android app.
Kotlin with
fetchClientThe
fetchClientmethod returns a client immediately and starts initializing the SDK in the background. It retries the communication with the reCAPTCHA server on network failures.class CustomApplication : Application () { private lateinit var recaptchaClient : RecaptchaClient // we recommend initializing in a ViewModel private val recaptchaScope = CoroutineScope ( Dispatchers . IO ) override fun onCreate () { super . onCreate () initializeRecaptchaClient () } private fun initializeRecaptchaClient () { recaptchaScope . launch { try { recaptchaClient = Recaptcha . fetchClient ( application , " KEY_ID " ) } catch ( e : RecaptchaException ) { // Handle errors ... // See "Handle errors" section } } } }Java with
fetchClientpublic final class CustomApplication extends Application { @Nullable private RecaptchaTasksClient recaptchaTasksClient = null ; @Override protected void onCreate () { super . onCreate (); initializeRecaptchaClient (); } private void initializeRecaptchaClient () { Recaptcha . fetchTaskClient ( getApplication (), " KEY_ID " ) . addOnSuccessListener ( this , new OnSuccessListener<RecaptchaTasksClient> () { @Override public void onSuccess ( RecaptchaTasksClient client ) { MainActivity . this . recaptchaTasksClient = client ; } }) . addOnFailureListener ( this , new OnFailureListener () { @Override public void onFailure ( @NonNull Exception e ) { // Handle errors ... // See "Handle errors" section } }); } }Initialization of the SDK can take several seconds to complete. To mitigate this latency, initialize the client as early as possible, such as during the
onCreate()call of a customApplicationclass. You shouldn't make UI elements block on the reCAPTCHA SDK. -
For each action of your app that is protected using reCAPTCHA, call the
executemethod passing a RecaptchaAction . reCAPTCHA provides a built-in set of actions and if necessary you can create custom actions.The following code snippet shows how to use
executeto protect aLOGINaction.Kotlin
private fun executeLoginAction () { recaptchaScope . launch { recaptchaClient . execute ( RecaptchaAction . LOGIN ) . onSuccess { token - > // Handle success ... // See "What's next" section for instructions // about handling tokens. } . onFailure { exception - > // Handle errors ... } } }Java
private void executeLoginAction ( View v ) { assert recaptchaTasksClient != null ; recaptchaTasksClient . executeTask ( RecaptchaAction . LOGIN ) . addOnSuccessListener ( this , new OnSuccessListener<String> () { @Override public void onSuccess ( String token ) { // Handle success ... // See "What's next" section for instructions // about handling tokens. } }) . addOnFailureListener ( this , new OnFailureListener () { @Override public void onFailure ( @NonNull Exception e ) { // Handle errors ... } }); }
Migrate from getClient method to fetchClient method
The fetchClient
method returns a RecaptchaClient
that retries initialization over network failures. If the app doesn't have
network access when the client is created, the client keeps retrying and
successfully initializes when a network is acquired.
If you call execute(timeout)
and the client is not yet ready, it tries
to initialize before returning a token or a RecaptchaErrorCode
.
The following example shows how to migrate from getClient
to fetchClient
.
Kotlin
// Migrate from getClient
private
fun
initializeWithGetClient
()
{
recaptchaScope
.
launch
{
Recaptcha
.
getClient
(
application
,
" KEY_ID
"
)
.
onSuccess
{
client
-
>
recaptchaClient
=
client
}
.
onFailure
{
exception
-
>
// Handle errors ...
}
}
}
// Migrate to fetchClient
private
fun
initializeWithFetchClient
()
{
recaptchaScope
.
launch
{
try
{
recaptchaClient
=
Recaptcha
.
fetchClient
(
application
,
" KEY_ID
"
)
}
catch
(
e
:
RecaptchaException
){
// Handle errors ...
}
}
}
Java
// Migrate from getTasksClient
private
void
initializeWithGetTasksClient
()
{
Recaptcha
.
getTasksClient
(
getApplication
(),
" KEY_ID
"
)
.
addOnSuccessListener
(
this
,
new
OnSuccessListener<RecaptchaTasksClient>
()
{
@Override
public
void
onSuccess
(
RecaptchaTasksClient
client
)
{
recaptchaTasksClient
=
client
;
}
})
.
addOnFailureListener
(
this
,
new
OnFailureListener
()
{
@Override
public
void
onFailure
(
@NonNull
Exception
e
)
{
// Handle errors ...
}
});
}
// Migrate to fetchTaskClient
private
void
initializeWithFetchTaskClient
()
{
Recaptcha
.
fetchTaskClient
(
getApplication
(),
" KEY_ID
"
)
.
addOnSuccessListener
(
this
,
new
OnSuccessListener<RecaptchaTasksClient>
()
{
@Override
public
void
onSuccess
(
RecaptchaTasksClient
client
)
{
recaptchaTasksClient
=
client
;
}
})
.
addOnFailureListener
(
this
,
new
OnFailureListener
()
{
@Override
public
void
onFailure
(
@NonNull
Exception
e
)
{
// Handle errors ...
}
});
}
Set a timeout for API calls
You can specify a timeout value for the execute
APIs by using the withTimeout
property.
Kotlin
-
Set timeout when calling
execute.recaptchaScope . launch { recaptchaClient . execute ( RecaptchaAction . LOGIN (), timeout = 10000L ) . onSuccess { token - > // Handle success ... // See "What's next" section for instructions // about handling tokens. } . onFailure { exception - > // Handle errors ... // See "Handle errors" section } }This code snippet sets the timeout of
executeto 10 seconds.
Java
-
Set timeout when calling
execute.recaptchaTasksClient . executeTask ( RecaptchaAction . custom ( "redeem" ), 10000L ) . addOnSuccessListener ( this , new OnSuccessListener<String> () { @Override public void onSuccess ( String token ) { // Handle success ... // See "What's next" section for instructions // about handling tokens. } }) . addOnFailureListener ( this , new OnFailureListener () { @Override public void onFailure ( @NonNull Exception e ) { // Handle errors ... // See "Handle errors" section } });This code snippet sets the timeout of
executeto 10 seconds.
Handle errors
If your app cannot communicate with the reCAPTCHA service successfully, it might be because the API encountered an error. You must add logic in your app to gracefully handle such errors.
For more details about mitigations for common API errors, see RecaptchaErrorCode .
API reference
For a complete reference of the reCAPTCHA API for Android,
see com.google.android.recaptcha
.
What's next
-
To assess the reCAPTCHA response token, create an assessment .
