Navigation SDK for iOS mit App Check schützen

Die Unterstützung für App Check mit dem Navigation SDK for iOS wird in den nächsten Tagen eingeführt. Wenn Sie diese Funktion noch nicht in der Firebase Console sehen, versuchen Sie es in ein paar Tagen noch einmal.

Firebase App Check schützt Anrufe von Ihrer App an Google Maps Platform, indem Traffic blockiert wird, der nicht von Ihren legitimen Apps stammt. Dazu wird eine Bewertung der Authentizität der App oder des Geräts von einem Bestätigungsanbieter wie App Attest angefordert. Wenn Sie Ihre App in App Check einbinden, schützen Sie sie vor böswilligen und nicht autorisierten Anfragen, wodurch wiederum Ihre Abrechnung vor nicht autorisierten Gebühren geschützt wird. App Check verbessert auch die Berichterstellung zu Störungen in Echtzeit in Ihrem Flotten-App-Ökosystem erheblich, was allen Fahrern zugutekommt, die Ihre App verwenden. Weitere Informationen finden Sie unter Berichte zu Störungen.

Wichtig:App Check blockiert nicht autorisierten Traffic nicht standardmäßig. Sie müssen die Erzwingung manuell aktivieren, nachdem Sie Ihre App-Messwerte überprüft haben (siehe Schritt 6: App-Anfragen beobachten und über die Erzwingung entscheiden).

Warum App Check verwenden?

App Check schützt zwei verschiedene Bereiche des Navigation SDK for iOS: die Hauptnavigationsfunktion und die Berichterstellung zu Störungen.

Navigation

App Check hilft, Anfragen an das Haupt-Navigation SDK for iOS von böswilligen oder nicht autorisierten Quellen zu blockieren. Das schützt Ihr Projekt vor Abrechnungsbetrug und Kontingentüberschreitungen.

Berichte zu Störungen

App Check ist sehr empfehlenswert, wenn Ihre App die Berichterstellung zu Störungen in Echtzeit und Abstimmungsfunktionen unterstützt. Wenn Sie App Check aktivieren, erhalten Ihre Fahrer die genauesten Routen, die alle Echtzeit-Feedback berücksichtigen.

Warum App Check für die Berichterstellung wichtig ist:

• Hohe Anforderungen an die Vertrauenswürdigkeit von Meldungen zu Straßensperrungen:Ereignisse, die sich auf die Route auswirken, z. B. Straßensperrungen, können das Routingverhalten für alle Fahrer erheblich verändern. Um die Karte vor potenziellem Vandalismus, Spam oder ungenauen Berichten zu schützen, stützt sich die Moderationsinfrastruktur von Google für Störungen durch Straßensperrungen auf starke Signale zur Geräte- und App-Integrität.
• So werden Berichte von App Check validiert:Nutzerberichte und Abstimmungen, die über das Navigation SDK for iOS gesendet werden, enthalten das App Check-Token. Dieses wird vom Backend von Google verwendet, um die Legitimität des Feedbacks zu validieren, wodurch das Vertrauensniveau erhöht wird und es auf Auswirkungen auf die Live-Karte geprüft werden kann.
• Auswirkungen des Verzichts auf App Check:Berichte, die ohne gültiges App Check-Token eingereicht werden, werden mit einem Modell mit niedrigerem Vertrauensniveau bewertet und möglicherweise nur als stille Signale verarbeitet. Das bedeutet, dass Ihre Nutzer zwar weiterhin Berichte einreichen und abstimmen können, ihre Berichte aber weniger wahrscheinlich auf der Karte sichtbar sind oder sich auf die Routen anderer Fahrer auswirken. Außerdem ist eine zusätzliche Validierung erforderlich.

Ist App Check das Richtige für mich?

App Check wird in den meisten Fällen empfohlen. In den folgenden Szenarien ist App Check jedoch nicht erforderlich oder wird nicht unterstützt:

• Private oder experimentelle Apps:Wenn Ihre App nicht öffentlich zugänglich ist, ist App Check nicht erforderlich.
• Manipulierte Geräte:Die empfohlenen Attestierungsanbieter verhindern, dass das Navigation SDK for iOS auf nicht vertrauenswürdigen Geräten wie gerooteten oder jailbreakten Smartphones ausgeführt wird. Wenn Sie diese Geräte unterstützen möchten, stellen Sie einen benutzerdefinierten Bestätigungsanbieter bereit.

Übersicht über die Implementierungsschritte

Im Wesentlichen führen Sie die folgenden Schritte aus, um Ihre App in App Check einzubinden:

1. Fügen Sie Ihrer Anwendung Firebase hinzu.
2. Fügen Sie die App Check-Bibliothek hinzu und initialisieren Sie App Check.
3. Fügen Sie einen Tokenanbieter hinzu. In diesem Schritt wird der Bestätigungsanbieter Ihrer Wahl aufgerufen, um die Integrität des Geräts oder der App zu überprüfen.
4. Initialisieren Sie die Navigation API und die App Check API.
5. Aktivieren Sie das Debugging. Das ist bei der Entwicklung oder in Continuous Integration-Umgebungen (CI) nützlich.
6. Beobachten Sie Ihre App-Anfragen, bevor Sie die Erzwingung aktivieren. So können Sie App Check nahtlos erzwingen, ohne Ihre Nutzer zu stören.

Überlegungen bei der Planung einer App Check-Einbindung

• Kontingente für Bestätigungsanbieter:Für die von uns empfohlenen Bestätigungsanbieter DeviceCheck oder App Attest gelten Kontingente und Einschränkungen, die von Apple festgelegt wurden.
• Startlatenz:In den meisten Fällen werden Ihre Nutzer bei der normalen Verwendung keine Latenz feststellen, da App Check-Tokens auf dem Gerät im Cache gespeichert werden. Das System aktualisiert App Check-Tokens automatisch im Hintergrund, bevor sie ablaufen, um eine nahtlose Leistung zu gewährleisten. Wenn jedoch kein gültiges App Check-Token vorhanden ist, werden Ihre App-Nutzer beim Start eine gewisse Latenz feststellen. Diese Latenz tritt beispielsweise bei Kaltstarts auf, wenn ein im Cache gespeichertes Token abgelaufen ist oder fehlt.
• TTL für Tokens:Die Gültigkeitsdauer (Time to Live, TTL) bestimmt, wie lange das App Check-Token gültig ist, bevor es aktualisiert werden muss. Sie können diese Dauer in der Firebase Console auf 30 Minuten bis 7 Tage festlegen. Eine Dauer von 1 Stunde wird als sichere Baseline empfohlen. Das SDK versucht jedoch automatisch, Hintergrundaktualisierungen nach etwa der Hälfte der TTL-Dauer durchzuführen. Eine detaillierte Anleitung für die Console finden Sie in der Firebase App Check-Dokumentation.

App in App Check einbinden

Voraussetzungen und Anforderungen

• Eine App mit dem Navigation SDK for iOS Version 11.0 oder höher.
• Die Paket-ID der App.
• Ihre Team-ID auf dem Tab „Membership“ (Mitgliedschaft) in der Apple Developer Console.
• Wenn Sie DeviceCheck verwenden möchten, Ihre private Schlüsseldatei und die Schlüssel-ID.
• Sie müssen in der Google Cloud Console der Eigentümer der App sein.
• Die Projekt-ID Ihrer App in der Google Cloud Console.

Schritt 1: Firebase zu Ihrer App hinzufügen

Folgen Sie der Anleitung in der Firebase-Entwicklerdokumentation, um Ihrer App Firebase hinzuzufügen. Fügen Sie die Datei GoogleService-Info.plist unverändert auf der Stammebene Ihres Projekts hinzu.

Importieren Sie in der Datei AppDelegate die folgenden Module:

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

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

Schritt 2: App Check-Bibliothek hinzufügen und App Check initialisieren

Firebase bietet Anleitungen für jeden Standard-Bestätigungsanbieter. In diesen Anleitungen wird beschrieben, wie Sie ein Firebase-Projekt einrichten und die App Check-Bibliothek zu Ihrer App hinzufügen. Folgen Sie den Codebeispielen, um App Check zu initialisieren.

1. Folgen Sie der Firebase-Anleitung, um die App Check-Bibliothek hinzuzufügen:
   • Anleitung für App Attest.
   • Anleitung für DeviceCheck.
2. Initialisieren Sie App Check in AppDelegate:
   • Wenn Sie App Attest verwenden, erstellen Sie eine Implementierung von AppCheckProviderFactory und registrieren Sie sie, bevor Sie FirebaseApp.configure() aufrufen:

     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];

   • Wenn Sie stattdessen DeviceCheck verwenden, legen Sie die Factory mit dem folgenden Code fest:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

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

Schritt 3: Tokenanbieter hinzufügen

Hinweis:Wenn Ihre App auch andere Google Maps Platform-SDKs verwendet, die App Check unterstützen (z. B. das Places SDK), können Sie dieselbe Firebase App Check-Konfiguration verwenden. Sie müssen jedoch die Tokenanbieterschnittstelle implementieren und registrieren, die für jedes SDK spezifisch ist.

Erstellen Sie auf der Stammebene Ihrer App eine Datei mit dem Namen AppCheckTokenProvider oder, wenn Sie Objective-C verwenden, zwei Dateien mit den Namen AppCheckTokenProvider.h und AppCheckTokenProvider.m.

Diese Klasse muss dem Protokoll GMSAppCheckTokenProvider entsprechen und die Methode fetchAppCheckTokenWithCompletion implementieren.

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

Schritt 4: Navigation API und App Check API initialisieren

Initialisieren Sie das Navigation SDK for iOS (mit GMSServices) und registrieren Sie Ihre Tokenanbieterinstanz, indem Sie das gemeinsame undurchsichtige Diensthandle in GMSServices umwandeln:

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];

Schritt 5: Debugging aktivieren (optional)

Nachdem App Check für das Navigation SDK for iOS erzwungen wurde, können die Funktionen Ihrer App, die vom Navigation SDK for iOS abhängen, nicht in einem Simulator oder in einer Continuous Integration-Umgebung (CI) ausgeführt werden, da diese Umgebungen nicht als gültige Geräte gelten. Wenn Sie Ihre App während der Entwicklung und des Tests in diesen Umgebungen ausführen möchten, müssen Sie einen Debug-Build Ihrer App erstellen, der den App Check-Debug-Anbieter anstelle eines Produktions-Bestätigungsanbieters verwendet.

1. Konfigurieren Sie die Debug-Anbieter-Factory 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. Aktivieren Sie die Protokollierung in Ihrem Xcode-Projekt, starten Sie die App und suchen Sie im Console-Protokoll nach dem lokalen Debug-Token.
3. Kopieren Sie dieses Debug-Token und fügen Sie es in der Firebase Console hinzu. Weitere Informationen finden Sie in der Dokumentation zum Firebase App Check-Debug-Anbieter.

Schritt 6: App-Anfragen beobachten und über die Erzwingung entscheiden

Hinweis:Die Erzwingung ist nicht unbedingt erforderlich, damit die Überprüfung der Geräteintegrität für Berichte zu Störungen in Echtzeit genutzt werden kann. Für einen umfassenden Schutz vor Abrechnungsbetrug, Spoofing und Kontingentmissbrauch muss die Erzwingung jedoch auf Projektebene aktiviert werden.

Beobachten Sie vor der Aktivierung der Erzwingung Ihre App-Anfragen, um sicherzustellen, dass Sie legitime Nutzer nicht stören.

1. Rufen Sie in der Firebase Console den Bildschirm mit den App Check-Messwerten auf, um den Prozentsatz des bestätigten und nicht bestätigten Traffics zu sehen.
2. Wenn Sie sicher sind, dass der Großteil Ihres Traffics bestätigt ist und legitime Nutzer auf eine Version Ihrer App aktualisiert haben, die Ihre App Check-Implementierung enthält, aktivieren Sie die Erzwingung.
3. Sobald die Erzwingung aktiviert ist, lehnt App Check alle Zugriffe ohne gültiges App Check-Token ab.