API SafetyNet reCAPTCHA

Il servizio SafetyNet include un'API reCAPTCHA che puoi utilizzare per proteggere la tua app dal traffico dannoso.

reCAPTCHA è un servizio senza costi che utilizza un motore avanzato di analisi del rischio per proteggere la tua app da spam e altre azioni illecite. Se il servizio sospetta che l'utente che interagisce con la tua app possa essere un bot anziché un essere umano, mostra un CAPTCHA che deve essere risolto da un essere umano prima che la tua app possa continuare l'esecuzione.

Questo documento spiega come integrare l'API reCAPTCHA di SafetyNet nella tua app.

Termini di servizio aggiuntivi

Accedendo o utilizzando l'API reCAPTCHA, accetti i Termini di servizio delle API di Google e i seguenti Termini di servizio di reCAPTCHA. Prima di accedere alle API, leggi e comprendi tutti i termini e le norme applicabili.

Registra una coppia di chiavi reCAPTCHA

Per registrare una coppia di chiavi da utilizzare con l'API SafetyNet reCAPTCHA, vai al sito di registrazione di reCAPTCHA per Android, quindi completa la seguente sequenza di passaggi:

1. Nel modulo visualizzato, fornisci le seguenti informazioni:

   • Etichetta:un'etichetta univoca per la chiave. In genere, utilizzi il nome della tua azienda o organizzazione.
   • Tipo di reCAPTCHA:seleziona reCAPTCHA v2, poi reCAPTCHA Android.
   • Pacchetti: fornisci il nome del pacchetto di ogni app che utilizza questa chiave API. Affinché un'app possa utilizzare l'API, il nome del pacchetto che inserisci deve corrispondere esattamente al nome del pacchetto dell'app. Inserisci ogni nome del pacchetto su una riga separata.
   • Proprietari:aggiungi un indirizzo email per ogni persona della tua organizzazione che monitora i test reCAPTCHA della tua app.

2. Seleziona la casella di controllo Accetta i Termini di servizio di reCAPTCHA.

3. Invia avvisi ai proprietari:seleziona questa casella di controllo se vuoi ricevere email relative all'API reCAPTCHA, quindi fai clic su Invia.

4. Nella pagina successiva, le chiavi pubblica e privata vengono visualizzate rispettivamente nelle sezioni Chiave del sito e Chiave segreta. Utilizzi la chiave di sito quando invii la richiesta di verifica e la chiave segreta quando convalidi il token di risposta dell'utente.

Aggiungi la dipendenza dell'API SafetyNet

Prima di utilizzare l'API reCAPTCHA, aggiungi l'API SafetyNet al tuo progetto. Se utilizzi Android Studio, aggiungi questa dipendenza al file Gradle a livello di app. Per maggiori informazioni, vedi Configurazione dell'API SafetyNet.

Utilizzare l'API reCAPTCHA

Questa sezione descrive come chiamare l'API reCAPTCHA per inviare una richiesta di verifica CAPTCHA e ricevere il token di risposta dell'utente.

Inviare la richiesta di verifica

Per richiamare l'API SafetyNet reCAPTCHA, chiama il metodo verifyWithRecaptcha(). In genere, questo metodo corrisponde alla selezione di un elemento dell'interfaccia utente, ad esempio un pulsante, nell'attività dell'utente.

Quando utilizzi il metodo verifyWithRecaptcha() nella tua app, devi:

• Passa la chiave del sito API come parametro.
• Esegui l'override dei metodi onSuccess() e onFailure() per gestire entrambi i possibili risultati dell'attività di richiesta di verifica. In particolare, se l'API passa un'istanza di ApiException in onFailure(), devi gestire ogni possibile codice di stato che puoi recuperare utilizzando getStatusCode().

Il seguente snippet di codice mostra come richiamare questo metodo:

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

Convalidare il token di risposta dell'utente

Quando l'API reCAPTCHA esegue il metodo onSuccess(), l'utente ha completato correttamente la verifica CAPTCHA. Tuttavia, questo metodo indica solo che l'utente ha risolto correttamente il CAPTCHA. Devi comunque convalidare il token di risposta dell'utente dal server di backend.

Per scoprire come convalidare il token di risposta dell'utente, vedi Verifica della risposta dell'utente.