Utilizzare App Check per proteggere l'SDK Navigation per iOS

Il supporto di App Check con l'SDK Navigation per iOS 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. Per farlo, richiede una valutazione dell'autenticità dell'app o del dispositivo da un provider di attestazione come App Attest. Quando integri la tua app con App Check, aggiungi protezione contro le richieste dannose e non autorizzate, che a loro volta proteggono 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 flotta, a vantaggio di tutti i conducenti che utilizzano la tua app. Per ulteriori informazioni, 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: monitorare le richieste dell'app e decidere l'applicazione forzata).

Perché utilizzare App Check?

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

Navigazione

App Check aiuta a bloccare le richieste principali dell'SDK Navigation per iOS da fonti dannose o non autorizzate. Questo ti avvantaggia direttamente proteggendo il tuo progetto da frodi di fatturazione e 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 vandalici, 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.
• In che modo App Check convalida le segnalazioni: le segnalazioni e i voti degli utenti inviati dall'SDK Navigation per iOS 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 iOS su dispositivi non attendibili, come smartphone rooted o jailbroken. Per supportare questi dispositivi, 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 operazione è 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: i provider di attestazione che consigliamo, DeviceCheck o App Attest, sono soggetti a quote e limitazioni impostate da Apple.
• Latenza di avvio: nella maggior parte delle situazioni, 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 token: il valore TTL (Time to Live) determina la durata 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 di sicurezza, 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 iOS versione 11.0 o successive installata.
• L'ID pacchetto dell'app.
• Il tuo ID team dalla scheda Appartenenza nella console Apple Developer.
• Se prevedi di utilizzare DeviceCheck, il file della chiave privata e l'ID chiave.
• 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 GoogleService-Info.plist, senza modifiche, al livello root del progetto.

Nel file AppDelegate, importa i seguenti moduli:

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

@import FirebaseCore;
@import FirebaseAppCheck;
@import GoogleNavigation;

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

Firebase fornisce istruzioni per ogni provider di attestazione predefinito. Queste istruzioni mostrano come configurare un progetto Firebase e aggiungere la libreria App Check alla tua app. Segui gli esempi di codice forniti per inizializzare App Check.

1. Segui le istruzioni di Firebase per aggiungere la libreria App Check:
   • Istruzioni per App Attest.
   • Istruzioni per DeviceCheck.
2. Inizializza App Check in AppDelegate:
   • Se utilizzi App Attest, crea un'implementazione di AppCheckProviderFactory e registrala prima di chiamare FirebaseApp.configure():

     Swift

     class YourAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
         func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
             return AppAttestProvider(app: app)
         }
     }
     // In application(_:didFinishLaunchingWithOptions:)
     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)
     FirebaseApp.configure()

     Objective-C

     #import <FirebaseCore/FirebaseCore.h>
     #import <FirebaseAppCheck/FirebaseAppCheck.h>
     
     @interface YourAppCheckProviderFactory : NSObject <FIRAppCheckProviderFactory>
     @end
     
     @implementation YourAppCheckProviderFactory
     - (nullable id<FIRAppCheckProvider>)createProviderWithApp:(FIRApp *)app {
         return [[FIRAppAttestProvider alloc] initWithApp:app];
     }
     @end
     
     // In application:didFinishLaunchingWithOptions:
     YourAppCheckProviderFactory *providerFactory = [[YourAppCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
     [FIRApp configure];

   • Se utilizzi DeviceCheck, imposta la factory utilizzando quanto segue:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     FIRDeviceCheckProviderFactory *providerFactory = [[FIRDeviceCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];

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 file denominato AppCheckTokenProvider (o, se utilizzi Objective-C, due file denominati AppCheckTokenProvider.h e AppCheckTokenProvider.m) a livello root dell'app.

Questa classe deve essere conforme al protocollo GMSAppCheckTokenProvider e implementare il metodo fetchAppCheckTokenWithCompletion.

Swift

import Foundation
import FirebaseAppCheck
import GoogleNavigation

class AppCheckTokenProvider: NSObject, GMSAppCheckTokenProvider {
    func fetchAppCheckToken(completion: @escaping (String?, Error?) -> Void) {
        AppCheck.appCheck().token(forcingRefresh: false) { token, error in
            if let error = error {
                print("App Check Error: \(error)")
                completion(nil, error)
                return
            }
            guard let token = token else {
                completion(nil, NSError(domain: "AppCheck", code: -1, userInfo: [NSLocalizedDescriptionKey: "Token is nil"]))
                return
            }
            print("App Check Token: \(token.token)")
            completion(token.token, nil)
        }
    }
}

Objective-C

// AppCheckTokenProvider.h
#import <Foundation/Foundation.h>
#import <GoogleNavigation/GoogleNavigation.h>

NS_ASSUME_NONNULL_BEGIN

@interface AppCheckTokenProvider : NSObject <GMSAppCheckTokenProvider>
@end

NS_ASSUME_NONNULL_END

// AppCheckTokenProvider.m
#import "AppCheckTokenProvider.h"
#import <FirebaseAppCheck/FirebaseAppCheck.h>

@implementation AppCheckTokenProvider
- (void)fetchAppCheckTokenWithCompletion:(void (^)(NSString * _Nullable token, NSError * _Nullable error))completion {
    [[FIRAppCheck appCheck] tokenForcingRefresh:NO
                                     completion:^(FIRAppCheckToken * _Nullable token, NSError * _Nullable error) {
        if (token) {
            completion(token.token, nil);
        } else {
            completion(nil, error);
        }
    }];
}
@end

Passaggio 4: inizializza le API Navigation e App Check

Inizializza l'SDK Navigation per iOS (utilizzando GMSServices) e registra l'istanza del provider di token eseguendo il cast dell'handle dei servizi opachi condivisi a GMSServices:

Swift

// In application(_:didFinishLaunchingWithOptions:)
GMSServices.provideAPIKey("YOUR_API_KEY")

// Register your App Check token provider before initializing Navigation SDK for iOS
if let services = GMSServices.sharedServices() as? GMSServices {
    services.appCheckTokenProvider = AppCheckTokenProvider()
}

Objective-C

// In application:didFinishLaunchingWithOptions:
[GMSServices provideAPIKey:@"YOUR_API_KEY"];

// Register your App Check token provider before initializing Navigation SDK for iOS
((GMSServices *)[GMSServices sharedServices]).appCheckTokenProvider = [[AppCheckTokenProvider alloc] init];

Passaggio 5: attiva il debug (facoltativo)

Dopo che App Check è stato applicato forzatamente per l'SDK Navigation per iOS, le funzionalità dell'app che dipendono dall'SDK Navigation per iOS 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 il 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. Configura la factory del provider di debug in AppDelegate:

   Swift

   #if targetEnvironment(simulator)
   let providerFactory = AppCheckDebugProviderFactory()
   #else
   let providerFactory = YourAppCheckProviderFactory()
   #endif
   AppCheck.setAppCheckProviderFactory(providerFactory)

   Objective-C

   #if TARGET_OS_SIMULATOR
   id<FIRAppCheckProviderFactory> providerFactory = [[FIRAppCheckDebugProviderFactory alloc] init];
   #else
   id<FIRAppCheckProviderFactory> providerFactory = [[YourAppCheckProviderFactory alloc] init];
   #endif
   [FIRAppCheck setAppCheckProviderFactory:providerFactory];

2. Attiva la registrazione nel progetto Xcode, avvia l'app e individua il token di debug locale nel log della console.
3. Copia e aggiungi questo token di debug alla 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 di interruzione 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.