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 di analisi del rischio avanzato 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 a essere eseguita.

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 vigenti.

Termini di servizio di reCAPTCHA

L'utente riconosce e accetta che l'API reCAPTCHA funziona tramite la raccolta di informazioni relative all'hardware e al software, ad esempio dati del dispositivo e delle applicazioni e i risultati dei controlli di integrità, e l'invio di questi dati a Google per l'analisi. Ai sensi della Sezione 3(d) dei Termini di servizio delle API di Google, l'utente accetta che, in caso di utilizzo delle API, è sua responsabilità fornire le notifiche o i consensi necessari per la raccolta e la condivisione dei dati con Google.

Registra una coppia di chiavi reCAPTCHA

Per registrare una coppia di chiavi da utilizzare con l'API reCAPTCHA di SafetyNet, 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 tua azienda o organizzazione.
    • Tipo di reCAPTCHA: seleziona reCAPTCHA v2, quindi 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 inserito 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 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, quindi fai clic su Invia.

  4. Nella pagina visualizzata successivamente, le chiavi pubblica e privata vengono visualizzate rispettivamente in Chiave del sito e Chiave segreta. Utilizza 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 dall'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 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.

Invia la richiesta di verifica

Per richiamare l'API reCAPTCHA di SafetyNet, chiama il metodo verifyWithRecaptcha(). In genere, questo metodo corrisponde alla selezione da parte dell'utente di un elemento dell'interfaccia utente, come un pulsante, nella tua attività.

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

  • Passa la chiave del sito API come parametro.
  • Sostituisci i 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:

Kotlin

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}")
                }
            })
}

Java

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());
                    }
                }
        });
}

Convalida il token di risposta dell'utente

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

Per scoprire come convalidare il token di risposta dell'utente, consulta la sezione Verificare la risposta dell'utente.