API SafetyNet Navigazione sicura

L'API Navigazione sicura di SafetyNet, una libreria basata su Google Play Services, fornisce servizi per determinare se un URL è stato contrassegnato da Google come una minaccia nota.

La tua app può utilizzare questa API per determinare se un determinato URL è stato classificato da Google come una minaccia nota. Internamente, SafetyNet implementa un client per il protocollo v4 di Navigazione sicura sviluppato da Google. Sia il codice client sia il protocollo di rete v4 sono progettati per preservare la privacy degli utenti e contenere al minimo il consumo di batteria e larghezza di banda. Utilizza questa API per sfruttare al meglio il servizio Navigazione sicura di Google su Android nel modo più ottimizzato per le risorse e senza implementare il relativo protocollo di rete.

Questo documento spiega come utilizzare l'API SafetyNet Navigazione sicura per verificare la presenza di minacce note in un URL.

Termini di servizio

Se utilizzi l'API Navigazione sicura, accetti di essere vincolato dai Termini di servizio. Prima di accedere all'API Safe Browsing, leggi e comprendi tutti i termini e le norme vigenti.

Richiedi e registra una chiave API per Android

Prima di utilizzare l'API Safe Browsing, crea e registra una chiave API Android. Per i passaggi specifici, consulta la pagina relativa alla guida introduttiva a Navigazione sicura.

Aggiungi la dipendenza dall'API SafetyNet

Prima di utilizzare l'API Navigazione sicura, 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 Proteggersi dalle minacce alla sicurezza con SafetyNet.

Inizializzare l'API

Per utilizzare l'API Navigazione sicura, devi inizializzala chiamando initSafeBrowsing() e attendere il completamento. Il seguente snippet di codice fornisce un esempio:

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing())

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing());

Richiedere il controllo di un URL

La tua app può utilizzare un controllo dell'URL per determinare se un URL rappresenta una minaccia nota. Alcuni tipi di minacce potrebbero non essere di interesse per la tua app specifica. L'API consente di scegliere quali tipi di minacce sono importanti per le tue esigenze. Puoi specificare più tipi di minacce note.

Invia la richiesta di controllo dell'URL

L'API è indipendente dallo schema utilizzato, quindi puoi passare l'URL con o senza uno schema. Ad esempio, sia

var url = "https://www.google.com"

String url = "https://www.google.com";

e

var url = "www.google.com"

String url = "www.google.com";

siano validi.

Il seguente codice mostra come inviare una richiesta di controllo dell'URL:

SafetyNet.getClient(this).lookupUri(
       url,
       SAFE_BROWSING_API_KEY,
       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING
)
       .addOnSuccessListener(this) { sbResponse ->
           // Indicates communication with the service was successful.
           // Identify any detected threats.
           if (sbResponse.detectedThreats.isEmpty()) {
               // No threats found.
           } else {
               // Threats found!
           }
       }
       .addOnFailureListener(this) { e: Exception ->
           if (e is ApiException) {
               // An error with the Google Play Services API contains some
               // additional details.
               Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")

               // Note: If the status code, s.statusCode,
               // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
               // you need to call initSafeBrowsing(). It means either you
               // haven't called initSafeBrowsing() before or that it needs
               // to be called again due to an internal error.
           } else {
               // A different, unknown type of error occurred.
               Log.d(TAG, "Error: ${e.message}")
           }
       }

SafetyNet.getClient(this).lookupUri(url,
         SAFE_BROWSING_API_KEY,
         SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
         SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
   .addOnSuccessListener(this,
       new OnSuccessListener<SafetyNetApi.SafeBrowsingResponse>() {
           @Override
           public void onSuccess(SafetyNetApi.SafeBrowsingResponse sbResponse) {
               // Indicates communication with the service was successful.
               // Identify any detected threats.
               if (sbResponse.getDetectedThreats().isEmpty()) {
                   // No threats found.
               } else {
                   // Threats found!
               }
        }
   })
   .addOnFailureListener(this, new OnFailureListener() {
           @Override
           public void onFailure(@NonNull Exception e) {
               // An error occurred while communicating with the service.
               if (e instanceof ApiException) {
                   // An error with the Google Play Services API contains some
                   // additional details.
                   ApiException apiException = (ApiException) e;
                   Log.d(TAG, "Error: " + CommonStatusCodes
                       .getStatusCodeString(apiException.getStatusCode()));

                   // Note: If the status code, apiException.getStatusCode(),
                   // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
                   // you need to call initSafeBrowsing(). It means either you
                   // haven't called initSafeBrowsing() before or that it needs
                   // to be called again due to an internal error.
               } else {
                   // A different, unknown type of error occurred.
                   Log.d(TAG, "Error: " + e.getMessage());
               }
           }
   });

Leggi la risposta di controllo dell'URL

Utilizza l'oggetto SafetyNetApi.SafeBrowsingResponse restituito, chiama il suo metodo getDetectedThreats(), che restituisce un elenco di SafeBrowsingThreat oggetti. Se l'elenco restituito è vuoto, l'API non ha rilevato alcuna minaccia nota. Se l'elenco non è vuoto, chiama getThreatType() su ogni elemento dell'elenco per determinare quali minacce note sono state rilevate dall'API.

Per visualizzare il testo dell'avviso suggerito, consulta la Guida per gli sviluppatori dell'API Navigazione sicura.

Specifica i tipi di minacce di tuo interesse

Le costanti della classe SafeBrowsingThreat contengono i tipi di minacce attualmente supportati:

Quando utilizzi l'API, aggiungi le costanti di tipo di minaccia come argomenti. Puoi aggiungere tutte le costanti di tipo di minaccia richieste dalla tua app, ma puoi utilizzare solo quelle non contrassegnate come ritirate.

Arrestare la sessione di Navigazione sicura

Se la tua app non deve utilizzare l'API Navigazione sicura per un periodo prolungato, controlla tutti gli URL necessari all'interno dell'app e poi chiudi la sessione di Navigazione sicura utilizzando il metodo shutdownSafeBrowsing():

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

Ti consigliamo di chiamare shutdownSafeBrowsing() nel metodo onPause() dell'attività e di chiamare initSafeBrowsing() nel metodo onResume() dell'attività. Tuttavia, assicurati che l'esecuzione di initSafeBrowsing() sia terminata prima di invocare lookupUri(). Assicurati che la sessione sia sempre aggiornata per ridurre la possibilità di errori interni nell'app.

Dati raccolti dall'API SafetyNet Navigazione sicura

L'API Navigazione sicura di SafetyNet raccoglie automaticamente i seguenti dati quando dialoga con il servizio Navigazione sicura su Android:

Cerchiamo di essere il più trasparenti possibili, ma sei l'unico responsabile della decisione su come rispondere al modulo della sezione Sicurezza dei dati di Google Play per quanto riguarda le modalità di raccolta, condivisione e sicurezza dei dati utente della tua app.