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 dei rischi 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é un essere umano, fornisce un CAPTCHA che un essere umano deve risolvere 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. Leggi e comprendi tutti i termini e le norme applicabili prima di accedere alle API.

Termini di servizio di reCAPTCHA

L'utente riconosce e accetta che l'API reCAPTCHA funziona raccogliendo informazioni relative all'hardware e al software, ad esempio dati del dispositivo e delle applicazioni e i risultati dei controlli di integrità, e inviando questi dati a Google per l'analisi. Conformemente alla Sezione 3(d) dei Termini di servizio delle API di Google, l'utente accetta che, in caso di utilizzo delle API, è sua responsabilità informare gli utenti oppure ottenere il consenso 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 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 dell'azienda o dell'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 che inserisci deve corrispondere esattamente al nome del pacchetto dell'app. Inserisci ogni nome di pacchetto in 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 sull'API reCAPTCHA, quindi fai clic su Invia.

  4. Nella pagina successiva, le chiavi pubbliche e private vengono visualizzate rispettivamente in Chiave 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 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 saperne di più, consulta la sezione Configurazione dell'API SafetyNet.

Utilizza 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 SafetyNet reCAPTCHA, chiama il metodo verifyWithRecaptcha(). In genere, questo metodo corrisponde alla selezione da parte dell'utente di un elemento UI, ad esempio un pulsante, nella tua attività.

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

  • Passa la chiave di sito dell'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:

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 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 tuo server di backend.

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