Questa pagina spiega come integrare reCAPTCHA Enterprise nella tua app per Android.
Se vuoi fornire verifiche visive per traffico sospetto, puoi utilizzare l'API reCAPTCHA SafetyNet.
Prima di iniziare
Crea una chiave reCAPTCHA per la piattaforma di app Android.
In alternativa, puoi copiare l'ID di una chiave reCAPTCHA esistente per Android eseguendo uno dei seguenti passaggi:
Per copiare l'ID di una chiave esistente dalla console Google Cloud, segui questi passaggi:
Vai alla pagina reCAPTCHA Enterprise.
- Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore del mouse sulla chiave da copiare, quindi fai clic su .
- Per copiare l'ID di una chiave esistente utilizzando l'API REST, usa il metodo projects.keys.list.
- Per copiare l'ID di una chiave esistente utilizzando l'interfaccia a riga di comando gcloud, utilizza il comando gcloud recaptcha Keys list.
Prepara l'ambiente Android
Android nativo
Prepara l'ambiente di sviluppo scaricando e installando l'ultima versione di Android Studio.
Assicurati di avere un'app con il valore minimo dell'SDK Android impostato su API 19: Android 4.4 (Lollipop). Puoi impostare l'SDK minimo della tua app su API 19 o creare una nuova app mobile.
Se crei una nuova app mobile, crea un'applicazione di test avviando un nuovo progetto Android Studio:
- Seleziona Attività vuota. Se vuoi utilizzare Jetpack Compose nella tua app, scegli Attività di scrittura vuota.
- Imposta la lingua su kotlin.
- Imposta il valore minimo dell'SDK su API 19: Android 4.4 (Lollipop).
Assicurati che il repository Maven
google()
di Google sia nell'elenco dei repository nel filebuild.gradle
a livello di progetto, come mostrato nel seguente snippet:allprojects { repositories { google() } }
Per ulteriori informazioni, consulta il Repository Maven di Google.
Per aggiungere la dipendenza dell'API reCAPTCHA Enterprise, aggiungi la seguente regola di build alla sezione
dependencies
del filebuild.gradle
a livello di app.implementation 'com.google.android.recaptcha:recaptcha:18.3.0'
Per ulteriori informazioni sull'aggiunta di dipendenze nelle app per Android, consulta Aggiungere dipendenze di build.
Aggiungi l'autorizzazione Internet tra il primo tag
<manifest>
e il primo tag<application>
nel file manifest dell'applicazione (ad esempioAndroidManifest.xml
). Questa autorizzazione è necessaria perché l'API reCAPTCHA Enterprise prevede operazioni di rete.<manifest ...> <uses-permission android:name="android.permission.INTERNET" /> <application ...> ... </application> </manifest>
Se vuoi utilizzare le librerie
AndroidX
nel nuovo progetto, compila l'SDK in Android 9.0 o versioni successive e aggiungi il seguente snippet di codice agradle.properties
.android.useAndroidX=true android.enableJetifier=true
Per ulteriori informazioni, consulta la sezione Migrazione ad AndroidX.
Flutter
Per istruzioni dettagliate sull'utilizzo di reCAPTCHA Enterprise tramite Flutter, consulta la documentazione di Flutter.
ReactNative
Per istruzioni dettagliate sull'utilizzo di reCAPTCHA Enterprise tramite React Native, consulta la documentazione relativa a React Native.
Integra reCAPTCHA Enterprise con la tua app per Android
Crea un'istanza di un client utilizzando la chiave reCAPTCHA (KEY_ID) che hai creato per la tua app 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. }
Per ogni azione della tua app protetta tramite reCAPTCHA Enterprise, chiama il metodo
execute
passando un RecaptchaAction. reCAPTCHA Enterprise fornisce un insieme integrato di azioni e, se necessario, puoi creare azioni personalizzate.Il seguente snippet di codice mostra come utilizzare
execute
per proteggere un'azioneLOGIN
.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 } }); }
Il seguente snippet di codice campione mostra un'integrazione completa dei metodi getClient()
e execute()
in una singola app Attività:
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
}
});
}
}
Imposta un timeout per le chiamate API
Puoi specificare un valore di timeout per le API getClient
e execute
utilizzando la proprietà timeout
di ogni API.
Un timeout predefinito di 10 secondi per getClient
e di 5 secondi per le
API execute
.
Kotlin
Imposta timeout per la chiamata al numero
getClient
.lifecycleScope.launch { Recaptcha.getClient(application, "KEY_ID", timeout = 20000L) .onSuccess { client -> recaptchaClient = client } .onFailure { exception -> // Handle communication errors ... // See "Handle communication errors" section } }
Questo snippet di codice imposta il timeout di
getClient
su 20 secondi.Imposta timeout per la chiamata al numero
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 } }
Questo snippet di codice imposta il timeout di
execute
su 10 secondi.
Java
Imposta timeout per la chiamata al numero
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 } });
Questo snippet di codice imposta il timeout di
getClient
su 20 secondi.Imposta timeout per la chiamata al numero
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 } });
Questo snippet di codice imposta il timeout di
execute
su 10 secondi.
Gestire gli errori di comunicazione
Se la tua app non riesce a comunicare correttamente con il servizio reCAPTCHA, è possibile che l'API abbia riscontrato un errore. Devi aggiungere una logica nell'app per gestire correttamente questi errori.
Per maggiori dettagli sulle mitigazioni degli errori comuni dell'API, consulta RecaptchaErrorCode.
Riferimento API
Per un riferimento completo dell'API reCAPTCHA per Android,
visita com.google.android.recaptcha
.
Passaggi successivi
Per valutare il token di risposta a reCAPTCHA, crea una valutazione.