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é una persona, mostra un CAPTCHA che una persona deve risolvere prima che l'app possa continuare l'esecuzione.

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

Termini di servizio aggiuntivi

Accedendo all'API reCAPTCHA o utilizzandola, accetti i Termini di servizio delle API di Google e i seguenti Termini di servizio di reCAPTCHA. Leggi e comprendi tutti i termini e le norme applicabili prima di accedere alle API.

Registrare 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, si utilizza il nome della società o dell'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 nella relativa riga.
   • Proprietari: aggiungi un indirizzo email per ogni persona della tua organizzazione che monitora le valutazioni 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 sull'API reCAPTCHA, poi fai clic Invia.

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

Aggiungere 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 ulteriori informazioni, vedi Configurare l'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 verifyWithRecaptcha() metodo. In genere, questo metodo corrisponde alla selezione di un elemento dell'interfaccia utente, ad esempio un pulsante, nella tua attività.

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

• Passare la chiave del sito API come parametro.
• Eseguire 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 a 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 Verificare la risposta dell'utente.