Cette page explique comment intégrer reCAPTCHA Enterprise à votre application Android.
Si vous souhaitez proposer des tests visuels en cas de trafic suspect, vous pouvez utiliser l'API SafetyNet reCAPTCHA.
Avant de commencer
Créez une clé reCAPTCHA pour la plate-forme d'applications Android.
Vous pouvez également copier l'ID d'une clé reCAPTCHA existante pour Android en procédant de l'une des manières suivantes:
Pour copier l'ID d'une clé existante à partir de la console Google Cloud, procédez comme suit:
Accédez à la page reCAPTCHA Enterprise.
- Dans la liste des clés reCAPTCHA, pointez sur la clé que vous souhaitez copier, puis cliquez sur .
- Pour copier l'ID d'une clé existante à l'aide de l'API REST, utilisez la méthode projects.keys.list.
- Pour copier l'ID d'une clé existante à l'aide de la gcloud CLI, exécutez la commande gcloud recaptcha keys list.
Préparer votre environnement Android
Appareil Android natif
Préparez votre environnement de développement en téléchargeant et en installant la dernière version d'Android Studio.
Assurez-vous de disposer d'une application dont la valeur minimale du SDK Android est définie sur API 19 : Android 4.4 (KitKat). Vous pouvez soit définir le SDK minimal de votre application sur l'API 19, soit créer une application mobile.
Si vous créez une application mobile, créez une application de test en démarrant un nouveau projet Android Studio:
- Sélectionnez Empty Activity (Activité vide). Si vous souhaitez utiliser Jetpack Compose dans votre application, sélectionnez Empty Compose Activity (Activité Compose vide).
- Définissez la langue sur kotlin.
- Définissez la valeur minimale du SDK sur API 19: Android 4.4 (KitKat).
Assurez-vous que le dépôt Maven de Google
google()
figure dans la liste des dépôts du fichierbuild.gradle
au niveau du projet, comme indiqué dans l'extrait suivant:allprojects { repositories { google() } }
Pour en savoir plus, consultez la section Dépôt Maven de Google.
Pour ajouter la dépendance de l'API reCAPTCHA Enterprise, ajoutez la règle de compilation suivante à la section
dependencies
du fichierbuild.gradle
au niveau de l'application.implementation 'com.google.android.recaptcha:recaptcha:18.5.0-beta02'
Pour en savoir plus sur l'ajout de dépendances dans des applications Android, consultez Ajouter des dépendances de compilation.
Ajoutez une autorisation Internet entre la première balise
<manifest>
et la première balise<application>
du fichier manifeste de votre application (par exemple,AndroidManifest.xml
). Cette autorisation est requise, car l'API reCAPTCHA Enterprise implique des opérations réseau.<manifest ...> <uses-permission android:name="android.permission.INTERNET" /> <application ...> ... </application> </manifest>
Si vous souhaitez utiliser des bibliothèques
AndroidX
dans votre nouveau projet, compilez le SDK vers Android 9.0 ou version ultérieure et ajoutez l'extrait de code suivant à votregradle.properties
.android.useAndroidX=true android.enableJetifier=true
Pour en savoir plus, consultez Migrer vers AndroidX.
Flutter
Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA Enterprise via Flutter, consultez la documentation Flutter.
ReactNative
Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA Enterprise via React Native, consultez la documentation de React Native.
Intégrer reCAPTCHA Enterprise à votre application Android
Instanciez un client à l'aide de la clé reCAPTCHA (KEY_ID) que vous avez créée pour votre application Android.
Kotlin
class MainActivity : AppCompatActivity() { private lateinit var recaptchaClient: RecaptchaClient override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) initializeRecaptchaClient() // ... rest of onCreate code } private fun initializeRecaptchaClient() { lifecycleScope.launch { Recaptcha.getClient(application, "KEY_ID") .onSuccess { client -> recaptchaClient = client } .onFailure { exception -> // Handle communication errors ... // See "Handle communication errors" section } } } // ... rest of activity code. }
Java
public final class MainActivity extends Activity { @Nullable private RecaptchaTasksClient recaptchaTasksClient = null; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); initializeRecaptchaClient(); // ... rest of onCreate code } private void initializeRecaptchaClient() { Recaptcha .getTasksClient(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 communication errors ... // See "Handle communication errors" section } }); } // ... rest of activity code. }
Pour chaque action de votre application protégée par reCAPTCHA Enterprise, appelez la méthode
execute
en transmettant une RecaptchaAction. reCAPTCHA Enterprise fournit un ensemble intégré d'actions et, si nécessaire, vous pouvez créer des actions personnalisées.L'extrait de code suivant montre comment utiliser
execute
pour protéger une actionLOGIN
.Kotlin
private fun executeLoginAction() { lifecycleScope.launch { recaptchaClient .execute(RecaptchaAction.LOGIN) .onSuccess { token -> // Handle success ... // See "What's next" section for instructions // about handling tokens. } .onFailure { exception -> // Handle communication errors ... // See "Handle communication errors" section } } }
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 communication errors ... // See "Handle communication errors" section } }); }
L'exemple d'extrait de code suivant montre une intégration complète des méthodes getClient()
et execute()
dans une seule application Activity:
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var recaptchaClient: RecaptchaClient
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
initializeRecaptchaClient()
findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
}
private fun initializeRecaptchaClient() {
lifecycleScope.launch {
Recaptcha.getClient(application, "KEY_ID")
.onSuccess { client ->
recaptchaClient = client
}
.onFailure { exception ->
// Handle communication errors ...
// See "Handle communication errors" section
}
}
}
private fun executeLoginAction() {
lifecycleScope.launch {
recaptchaClient
.execute(RecaptchaAction.LOGIN)
.onSuccess { token ->
// Handle success ...
// See "What's next" section for instructions
// about handling tokens.
}
.onFailure { exception ->
// Handle communication errors ...
// See "Handle communication errors" section
}
}
}
private fun executeRedeemAction(){
lifecycleScope.launch {
recaptchaClient
.execute(RecaptchaAction.custom("redeem"))
.onSuccess { token ->
// Handle success ...
// See "What's next" section for instructions
// about handling tokens.
}
.onFailure { exception ->
// Handle communication errors ...
// See "Handle communication errors" section
}
}
}
}
Java
public final class MainActivity extends Activity {
@Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
initializeRecaptchaClient();
findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
}
private void initializeRecaptchaClient() {
Recaptcha
.getTasksClient(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 communication errors ...
// See "Handle communication errors" section
}
});
}
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 communication errors ...
// See "Handle communication errors" section
}
});
}
private void executeRedeemAction(View v) {
assert recaptchaTasksClient != null;
recaptchaTasksClient
.executeTask(RecaptchaAction.custom("redeem"))
.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 communication errors ...
// See "Handle communication errors" section
}
});
}
}
Définir un délai avant expiration pour les appels d'API
Vous pouvez spécifier une valeur de délai avant expiration pour les API getClient
et execute
à l'aide de la propriété timeout
de chaque API.
Un délai avant expiration par défaut de 10 secondes est utilisé pour getClient
et de 10 secondes pour les API execute
.
Kotlin
Définissez un délai d'inactivité lors de l'appel de
getClient
.lifecycleScope.launch { Recaptcha.getClient(application, "KEY_ID", timeout = 20000L) .onSuccess { client -> recaptchaClient = client } .onFailure { exception -> // Handle communication errors ... // See "Handle communication errors" section } }
Cet extrait de code définit le délai avant expiration de
getClient
sur 20 secondes.Définissez un délai d'inactivité lors de l'appel de
execute
.lifecycleScope.launch { recaptchaClient .execute(RecaptchaAction.LOGIN(), timeout = 10000L) .onSuccess { token -> // Handle success ... // See "What's next" section for instructions // about handling tokens. } .onFailure { exception -> // Handle communication errors ... // See "Handle communication errors" section } }
Cet extrait de code définit le délai avant expiration de
execute
sur 10 secondes.
Java
Définissez un délai d'inactivité lors de l'appel de
getClient
.Recaptcha .getTasksClient(getApplication(), "KEY_ID", 20000L) .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 communication errors ... // See "Handle communication errors" section } });
Cet extrait de code définit le délai avant expiration de
getClient
sur 20 secondes.Définissez un délai d'inactivité lors de l'appel de
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 communication errors ... // See "Handle communication errors" section } });
Cet extrait de code définit le délai avant expiration de
execute
sur 10 secondes.
Gérer les erreurs de communication
Si votre application ne peut pas communiquer avec le service reCAPTCHA, il se peut que l'API ait rencontré une erreur. Vous devez ajouter une logique dans votre application pour gérer correctement ces erreurs.
Pour en savoir plus sur les mesures d'atténuation des erreurs d'API courantes, consultez RecaptchaErrorCode.
Documentation de référence de l'API
Pour en savoir plus sur l'API reCAPTCHA pour Android, consultez com.google.android.recaptcha
.
Étapes suivantes
Pour évaluer le jeton de réponse reCAPTCHA, créez une évaluation.