Utilizzare App Check per proteggere l'SDK Navigation per Android

Il supporto di App Check con l'SDK Navigation per Android verrà implementato nei prossimi giorni. Se non vedi ancora questa funzionalità nella console Firebase, ricontrolla tra qualche giorno.

Firebase App Check fornisce protezione per le chiamate dalla tua app a Google Maps Platform bloccando il traffico proveniente da fonti diverse dalle tue app legittime. A questo scopo, richiede una valutazione dell'autenticità dell'app o del dispositivo da un provider di attestazione come Play Integrity. Quando integri la tua app con App Check, aggiungi protezione contro le richieste dannose e non autorizzate, che a sua volta protegge la fatturazione da addebiti non autorizzati. App Check migliora anche in modo significativo la segnalazione di interruzioni in tempo reale nell'ecosistema delle app della tua flotta, a vantaggio di tutti i conducenti che utilizzano la tua app. Per saperne di più, consulta Segnalazione di interruzioni.

Importante: per impostazione predefinita, App Check non blocca il traffico non autorizzato. Devi attivare manualmente l'applicazione forzata dopo aver verificato le metriche dell'app (vedi Passaggio 6: monitora le richieste dell'app e decidi l'applicazione forzata).

Perché utilizzare App Check?

App Check protegge due aree distinte dell'SDK Navigation per Android: la funzionalità di navigazione principale e la segnalazione di interruzioni.

Navigazione

App Check aiuta a bloccare le richieste principali dell'SDK Navigation per Android da fonti dannose o non autorizzate. Questo ti avvantaggia direttamente proteggendo il tuo progetto da frodi di fatturazione e dall'esaurimento della quota.

Segnalazione di interruzioni

App Check è vivamente consigliato se la tua app supporta le funzionalità di segnalazione e voto delle interruzioni in tempo reale. L'attivazione di App Check garantisce che i conducenti ricevano i percorsi più precisi tenendo conto di tutti i feedback in tempo reale.

Perché App Check è importante per la segnalazione:

• La barra di attendibilità elevata per le chiusure: gli eventi che influiscono sul percorso, come le chiusure stradali, possono alterare in modo significativo il comportamento di routing per tutti i conducenti. Per proteggere la mappa da potenziali atti di vandalismo, spam o segnalazioni inaccurate, l'infrastruttura di moderazione di Google per le interruzioni dovute a chiusure stradali si basa su indicatori di integrità dell'app e dei dispositivi affidabili.
• Come App Check convalida le segnalazioni: le segnalazioni e i voti degli utenti inviati dall'SDK Navigation per Android includono il token App Check, che viene utilizzato dal backend di Google per convalidare la legittimità del feedback, aumentandone il livello di attendibilità e consentendone la valutazione per l'impatto sulla mappa live.
• L'impatto dell'omissione di App Check: le segnalazioni inviate senza un token App Check valido vengono valutate in base a un modello di attendibilità inferiore e potrebbero essere elaborate solo come indicatori silenziosi. Ciò significa che, sebbene gli utenti possano comunque segnalare e votare, è meno probabile che le loro segnalazioni siano visibili sulla mappa o influiscano sui percorsi di altri conducenti e richiederanno una convalida aggiuntiva.

App Check è la soluzione giusta per me?

App Check è consigliato nella maggior parte dei casi; tuttavia, non è necessario o non è supportato nei seguenti scenari:

• App private o sperimentali: se la tua app non è accessibile pubblicamente, App Check non è necessario.
• Dispositivi compromessi: i provider di attestazione consigliati impediscono l'esecuzione dell'SDK Navigation per Android su dispositivi non attendibili, come smartphone rooted o jailbroken. Per supportare questi dispositivi, esegui il deployment di un provider di attestazione personalizzato.
• Dispositivi Android non GMS: i dispositivi Android devono eseguire Google Mobile Services (GMS) per Play Integrity. Se prevedi di supportare dispositivi Android non GMS, esegui il deployment di un provider di attestazione personalizzato.

Panoramica dei passaggi di implementazione

In linea generale, segui questi passaggi per integrare la tua app con App Check:

1. Aggiungi Firebase alla tua app.
2. Aggiungi la libreria App Check e inizializza App Check.
3. Aggiungi un provider di token. Questo passaggio richiama il provider di attestazione di tua scelta per verificare l'integrità del dispositivo o dell'app.
4. Inizializza le API Navigation e App Check.
5. Attiva il debug. Questa opzione è utile durante lo sviluppo o negli ambienti di integrazione continua (CI).
6. Monitora le richieste dell'app prima di attivare l'applicazione forzata. In questo modo, puoi applicare App Check senza problemi senza interrompere l'esperienza degli utenti.

Considerazioni sulla pianificazione di un'integrazione di App Check

• Quote del provider di attestazione: il provider di attestazione che consigliamo, Play Integrity, ha un limite di chiamate giornaliero per il livello di utilizzo dell'API Standard. Per saperne di più sui limiti di chiamata, consulta la pagina Configurazione nella documentazione per gli sviluppatori di Google Play Integrity.
• Latenza di avvio: nella maggior parte dei casi, gli utenti non riscontreranno latenza durante l'utilizzo normale, perché i token App Check vengono memorizzati nella cache del dispositivo. Il sistema aggiorna automaticamente i token App Check in background prima della scadenza per mantenere prestazioni ottimali. Tuttavia, se non è presente un token App Check valido, gli utenti dell'app riscontreranno una certa latenza all'avvio. Ad esempio, questa latenza si verifica durante gli avvii a freddo quando un token memorizzato nella cache è scaduto o mancante.
• TTL del token: il valore TTL (Time to Live) determina il periodo di validità del token App Check prima che debba essere aggiornato. Puoi configurare questa durata da 30 minuti a 7 giorni nella console Firebase. È consigliata una durata di 1 ora come base sicura, ma l'SDK tenta automaticamente gli aggiornamenti in background a circa metà della durata TTL. Per istruzioni dettagliate sulla console, consulta la documentazione di Firebase App Check.

Integrare l'app con App Check

Prerequisiti e requisiti

• Un'app con l'SDK Navigation per Android versione 7.9 o successive installata.
• La fingerprint del certificato SHA-256 della tua app.
• Il nome del pacchetto dell'app.
• Devi essere il proprietario dell'app nella console Google Cloud.
• L'ID progetto dell'app dalla console Google Cloud.

Passaggio 1: aggiungi Firebase alla tua app

Segui le istruzioni nella documentazione per gli sviluppatori di Firebase per aggiungere Firebase alla tua app. Aggiungi il file google-services.json alla directory a livello di app del tuo progetto.

Passaggio 2: aggiungi la libreria App Check e inizializza App Check

Aggiungi la dipendenza App Check al file build.gradle della tua app:

Groovy (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

Inizializza App Check nella classe Application o nell'attività principale:

Java

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

Passaggio 3: aggiungi il provider di token

Nota: se la tua app utilizza anche altri SDK Google Maps Platform che supportano App Check (ad esempio Places SDK), puoi utilizzare la stessa configurazione di Firebase App Check, ma devi implementare e registrare l'interfaccia del provider di token specifica per ogni SDK.

Crea un'implementazione dell'interfaccia MapsAppCheckTokenProvider. Questo provider recupera in modo asincrono i token App Check da Firebase App Check e li passa allo stack di rete dell'SDK Navigation per Android utilizzando MapsAppCheckTokenCallback:

Java

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

Passaggio 4: inizializza le API Navigation e App Check

Inizializza l'SDK Navigation per Android e registra l'istanza del provider di token unificato utilizzando MapsApiSettings.setAppCheckTokenProvider():

Java

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

Passaggio 5: attiva il debug (facoltativo)

Dopo aver applicato App Check per l'SDK Navigation per Android, le funzionalità dell'app che dipendono dall'SDK Navigation per Android non verranno eseguite in un simulatore o da un ambiente di integrazione continua (CI) perché questi ambienti non sono considerati dispositivi validi. Per eseguire l'app in questi ambienti durante lo sviluppo e i test, devi creare una build di debug dell'app che utilizzi il provider di debug di App Check anziché un provider di attestazione di produzione.

1. Aggiungi la dipendenza del provider di debug al file build.gradle della tua app:

   Groovy (build.gradle)

   dependencies {
       implementation 'com.google.firebase:firebase-appcheck-debug'
   }

2. Configura App Check in modo che utilizzi la factory del provider di debug nelle build di debug:

   Java

   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;
   
   if (BuildConfig.DEBUG) {
       firebaseAppCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       );
   } else {
       firebaseAppCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance()
       );
   }

   Kotlin

   import com.google.firebase.Firebase
   import com.google.firebase.appcheck.appCheck
   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
   
   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance(),
       )
   } else {
       Firebase.appCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance(),
       )
   }

3. Avvia l'app su un emulatore o un dispositivo di debug. App Check stamperà un token di debug locale nell'output logcat.
4. Copia e registra questo token di debug nella console Firebase. Per ulteriori dettagli, consulta la documentazione del provider di debug di Firebase App Check.

Passaggio 6: monitora le richieste dell'app e decidi l'applicazione forzata

Nota: l'applicazione forzata non è strettamente necessaria per consentire ai report sulle interruzioni in tempo reale di usufruire della verifica dell'integrità del dispositivo; tuttavia, la protezione completa da frodi di fatturazione, spoofing e abuso di quota si basa sull'attivazione dell'applicazione forzata a livello di progetto.

Prima di attivare l'applicazione forzata, monitora le richieste dell'app per assicurarti di non interrompere l'esperienza degli utenti legittimi.

1. Visita la schermata delle metriche di App Check nella console Firebase per visualizzare la percentuale di traffico verificato rispetto a quello non verificato.
2. Quando hai la certezza che la maggior parte del traffico è verificata e che gli utenti legittimi hanno eseguito l'aggiornamento a una versione dell'app contenente l'implementazione di App Check, attiva l'applicazione forzata.
3. Una volta attivata l'applicazione forzata, App Check rifiuterà tutto il traffico senza un token App Check valido.