Navigation SDK for Android mit App Check schützen

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 Attestierungsanbieter wie Play Integrity angefordert. Wenn Sie Ihre App in App Check einbinden, schützen Sie sie vor böswilligen und nicht autorisierten Anfragen. Dadurch wird auch Ihre Abrechnung vor nicht autorisierten Gebühren geschützt. App Check verbessert außerdem die Berichterstellung zu Störungen in Echtzeit im App-Ökosystem Ihrer Flotte erheblich, was allen Fahrern zugutekommt, die Ihre App verwenden. Weitere Informationen finden Sie unter Berichte zu Störungen.

Warum App Check verwenden?

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

Mit App Check können Sie Anfragen an das Haupt-Navigation SDK for Android von böswilligen oder nicht autorisierten Quellen blockieren. Das schützt Ihr Projekt vor Abrechnungsbetrug und Quota-Erschöpfung.

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 Zuverlässigkeit von 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 mit App Check validiert:Nutzerberichte und Abstimmungen, die über das Navigation SDK for Android gesendet werden, enthalten das App Check-Token. Dieses wird vom Backend von Google verwendet, um die Legitimität des Feedbacks zu validieren. Dadurch wird die Zuverlässigkeit erhöht und es kann bewertet werden, ob es sich auf die Live-Karte auswirkt.
  • Auswirkungen, wenn App Check nicht verwendet wird:Berichte, die ohne gültiges App Check-Token eingereicht werden, werden mit einem Modell mit geringerer Zuverlässigkeit 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 Android auf nicht vertrauenswürdigen Geräten wie gerooteten oder Jailbreak-Geräten ausgeführt wird. Wenn Sie diese Geräte unterstützen möchten, stellen Sie einen benutzerdefinierten Attestierungsanbieter bereit.
  • Android-Geräte ohne GMD:Auf Android-Geräten müssen die Google Mobile-Dienste (GMD) für Play Integrity ausgeführt werden. Wenn Sie Android-Geräte ohne GMD unterstützen möchten, stellen Sie einen benutzerdefinierten Attestierungsanbieter 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 Attestierungsanbieter 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 während 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 Attestierungsanbieter:Der von uns empfohlene Attestierungsanbieter Play Integrity hat ein tägliches Anruflimit für die Nutzungsstufe „Standard API“. Weitere Informationen zu Anruflimits finden Sie auf der Einrichtungsseite in der Entwicklerdokumentation zu Google Play Integrity.
  • 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.
  • Token-TTL: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 etwa bei der Hälfte der TTL-Dauer durchzuführen. Eine detaillierte Anleitung für die Console finden Sie in der Dokumentation zu Firebase App Check.

App in App Check einbinden

Voraussetzungen und Anforderungen

  • Eine App mit dem Navigation SDK for Android Version 7.9 oder höher.
  • Der SHA‑256-Zertifikat-Fingerabdruck Ihrer App.
  • Der Paketname Ihrer App.
  • Sie müssen in der Google Cloud Console der Eigentümer der App sein.
  • Die Projekt-ID Ihrer App aus 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 google-services.json dem Verzeichnis auf App-Ebene Ihres Projekts hinzu.

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

Fügen Sie der Datei build.gradle Ihrer App die App Check-Abhängigkeit hinzu:

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'
}

Initialisieren Sie App Check in Ihrer Application-Klasse oder Hauptaktivität:

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(),
)

Schritt 3: Tokenanbieter hinzufügen

Erstellen Sie eine Implementierung der Schnittstelle MapsAppCheckTokenProvider. Dieser Anbieter ruft App Check-Tokens asynchron von Firebase App Check ab und übergibt sie mit MapsAppCheckTokenCallback an den Netzwerk-Stack des Navigation SDK for Android:

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()
            }
    }
}

Schritt 4: Navigation API und App Check API initialisieren

Initialisieren Sie das Navigation SDK for Android und registrieren Sie Ihre einheitliche Tokenanbieterinstanz mit 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())

Schritt 5: Debugging aktivieren (optional)

Nachdem App Check für das Navigation SDK for Android erzwungen wurde, können die Funktionen Ihrer App, die vom Navigation SDK for Android 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-Attestierungsanbieters verwendet.

  1. Fügen Sie der Datei build.gradle Ihrer App die Debug-Anbieter-Abhängigkeit hinzu:

    Groovy (build.gradle)

    dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
  2. Konfigurieren Sie App Check so, dass die Debug-Anbieter-Factory in Ihren Debug-Builds verwendet wird:

    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. Starten Sie Ihre App auf einem Emulator oder Debug-Gerät. App Check gibt ein lokales Debug-Token in Ihrer Logcat-Ausgabe aus.
  4. Kopieren Sie dieses Debug-Token und registrieren Sie es in der Firebase Console. Weitere Informationen finden Sie in der Dokumentation zum Firebase App Check-Debug-Anbieter.

Schritt 6: App-Anfragen beobachten und Erzwingung festlegen

Beobachten Sie Ihre App-Anfragen, bevor Sie die Erzwingung aktivieren, damit Sie legitime Nutzer nicht stören.

  1. Auf dem Bildschirm mit den App Check-Messwerten in der Firebase Console sehen Sie den Prozentsatz des bestätigten und nicht bestätigten Traffics.
  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.