Menggunakan App Check untuk mengamankan Navigation SDK for Android

Dukungan untuk App Check dengan Navigation SDK for Android akan diluncurkan selama beberapa hari ke depan. Jika Anda belum melihat kemampuan ini di Firebase console, periksa kembali dalam beberapa hari.

Firebase App Check memberikan perlindungan untuk panggilan dari aplikasi Anda ke Google Maps Platform dengan memblokir traffic yang berasal dari sumber selain aplikasi sah Anda. Hal ini dilakukan dengan meminta evaluasi keaslian aplikasi atau perangkat dari penyedia pengesahan seperti Play Integrity. Saat mengintegrasikan aplikasi dengan App Check, Anda menambahkan perlindungan terhadap permintaan berbahaya dan tidak sah, yang pada gilirannya melindungi penagihan Anda dari tagihan yang tidak sah. App Check juga meningkatkan pelaporan gangguan real-time secara signifikan dalam ekosistem aplikasi armada Anda, sehingga menguntungkan semua pengemudi yang menggunakan aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat Pelaporan gangguan.

Penting: App Check tidak memblokir traffic yang tidak sah secara default. Anda harus mengaktifkan penerapan secara manual setelah memverifikasi metrik aplikasi (lihat Langkah 6: Pantau permintaan aplikasi dan tentukan penerapan).

Mengapa menggunakan App Check?

App Check melindungi dua area Navigation SDK for Android yang berbeda: fungsi navigasi utama dan pelaporan gangguan.

Navigasi

App Check membantu memblokir permintaan Navigation SDK for Android utama dari sumber berbahaya atau tidak sah. Hal ini secara langsung menguntungkan Anda dengan melindungi project dari penipuan tagihan dan kehabisan kuota.

Pelaporan gangguan

App Check sangat direkomendasikan jika aplikasi Anda mendukung kemampuan pelaporan dan voting gangguan real-time. Mengaktifkan App Check memastikan pengemudi Anda mendapatkan rute paling akurat yang memperhitungkan semua masukan real-time.

Mengapa App Check penting untuk pelaporan:

• Standar kepercayaan yang tinggi untuk penutupan: Peristiwa yang memengaruhi rute, seperti penutupan jalan, dapat mengubah perilaku perutean secara signifikan untuk semua pengemudi. Untuk melindungi peta dari potensi vandalisme, spam, atau pelaporan yang tidak akurat, infrastruktur moderasi Google untuk gangguan penutupan jalan mengandalkan sinyal integritas perangkat dan aplikasi yang kuat.
• Cara App Check memvalidasi laporan: Laporan dan voting pengguna yang dikirim dari Navigation SDK for Android menyertakan token App Check, yang digunakan oleh backend Google untuk memvalidasi legitimasi masukan, meningkatkan tingkat kepercayaannya, dan memungkinkannya dievaluasi untuk dampak peta langsung.
• Dampak jika tidak menggunakan App Check: Laporan yang dikirim tanpa token App Check yang valid dievaluasi berdasarkan model kepercayaan yang lebih rendah dan mungkin hanya diproses sebagai sinyal senyap. Artinya, meskipun pengguna Anda masih dapat melaporkan dan memberikan voting, laporan mereka cenderung tidak terlihat di peta atau memengaruhi rute pengemudi lain dan akan memerlukan validasi tambahan.

Apakah App Check tepat untuk saya?

App Check direkomendasikan dalam sebagian besar kasus; namun, App Check tidak diperlukan atau tidak didukung dalam skenario berikut:

• Aplikasi pribadi atau eksperimental: Jika aplikasi Anda tidak dapat diakses secara publik, App Check tidak diperlukan.
• Perangkat yang disusupi: Penyedia pengesahan yang direkomendasikan mencegah Navigation SDK for Android berjalan di perangkat yang tidak tepercaya, seperti ponsel yang di-root atau di-jailbreak. Untuk mendukung perangkat ini, deploy penyedia pengesahan kustom.
• Perangkat Android non-GMS: Perangkat Android harus menjalankan Layanan Seluler Google (GMS) untuk Play Integrity. Jika Anda berencana mendukung perangkat Android non-GMS, deploy penyedia pengesahan kustom.

Ringkasan langkah-langkah penerapan

Secara umum, Anda akan mengikuti langkah-langkah berikut untuk mengintegrasikan aplikasi dengan App Check:

1. Tambahkan Firebase ke aplikasi Anda.
2. Tambahkan library App Check dan lakukan inisialisasi App Check.
3. Tambahkan penyedia token. Langkah ini memanggil penyedia pengesahan pilihan Anda untuk memverifikasi integritas perangkat atau aplikasi.
4. Lakukan inisialisasi Navigation dan App Check API.
5. Aktifkan proses debug. Hal ini berguna selama pengembangan atau di lingkungan continuous integration (CI).
6. Pantau permintaan aplikasi Anda sebelum mengaktifkan penerapan. Dengan cara ini, Anda dapat menerapkan App Check dengan lancar tanpa mengganggu pengguna.

Pertimbangan saat merencanakan integrasi App Check

• Kuota Penyedia Pengesahan: Penyedia pengesahan yang kami rekomendasikan, Play Integrity, memiliki batas panggilan harian untuk tingkat penggunaan API Standarnya. Untuk mengetahui informasi selengkapnya tentang batas panggilan, lihat halaman Penyiapan di dokumentasi developer Google Play Integrity.
• Latensi Startup: Dalam sebagian besar situasi, pengguna tidak akan mengalami latensi selama penggunaan reguler, karena token App Check di-cache di perangkat. Sistem otomatis memperbarui token App Check di latar belakang sebelum masa berlakunya berakhir untuk mempertahankan performa yang lancar. Namun, jika token App Check yang valid tidak ada, pengguna aplikasi akan mengalami latensi saat startup. Misalnya, latensi ini terjadi selama cold start saat token yang di-cache sudah tidak berlaku atau tidak ada.
• TTL Token: Time to live (TTL) menentukan jumlah waktu token App Check berlaku sebelum perlu diperbarui. Anda dapat mengonfigurasi durasi ini dari 30 menit hingga 7 hari di Firebase console. Durasi 1 jam direkomendasikan sebagai dasar pengukuran yang aman, tetapi SDK otomatis mencoba pembaruan latar belakang pada sekitar setengah durasi TTL. Untuk petunjuk konsol langkah demi langkah, lihat dokumentasi Firebase App Check.

Mengintegrasikan aplikasi dengan App Check

Prasyarat dan persyaratan

• Aplikasi dengan Navigation SDK for Android versi 7.9 atau yang lebih baru terinstal.
• Sidik jari sertifikat SHA-256 aplikasi Anda.
• Nama paket aplikasi Anda.
• Anda harus menjadi pemilik aplikasi di Konsol Google Cloud.
• ID project aplikasi Anda dari Google Cloud console.

Langkah 1: Tambahkan Firebase ke aplikasi Anda

Ikuti petunjuk dalam dokumentasi developer Firebase untuk menambahkan Firebase ke aplikasi Anda. Tambahkan file google-services.json ke direktori tingkat aplikasi project Anda.

Langkah 2: Tambahkan library App Check dan lakukan inisialisasi App Check

Tambahkan dependensi App Check ke file build.gradle aplikasi Anda:

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

Lakukan inisialisasi App Check di class Aplikasi atau aktivitas utama Anda:

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

Langkah 3: Tambahkan penyedia token

Catatan: Jika aplikasi Anda juga menggunakan Google Maps Platform SDK lain yang mendukung App Check (seperti Places SDK), Anda dapat menggunakan konfigurasi Firebase App Check yang sama, tetapi Anda harus menerapkan dan mendaftarkan antarmuka penyedia token yang khusus untuk setiap SDK.

Buat implementasi antarmuka MapsAppCheckTokenProvider. Penyedia ini mengambil token App Check secara asinkron dari Firebase App Check dan meneruskannya ke Navigation SDK for Android network stack menggunakan 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()
            }
    }
}

Langkah 4: Lakukan inisialisasi Navigation dan App Check API

Lakukan inisialisasi Navigation SDK for Android dan daftarkan instance penyedia token terpadu Anda menggunakan 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())

Langkah 5: Aktifkan proses debug (opsional)

Setelah App Check diterapkan untuk Navigation SDK for Android, fitur aplikasi Anda yang bergantung pada Navigation SDK for Android tidak akan berjalan di simulator atau dari lingkungan continuous integration (CI) karena lingkungan ini tidak memenuhi syarat sebagai perangkat yang valid. Untuk menjalankan aplikasi di lingkungan ini selama pengembangan dan pengujian, Anda harus membuat build debug aplikasi yang menggunakan penyedia debug App Check, bukan penyedia pengesahan produksi.

1. Tambahkan dependensi penyedia debug ke file build.gradle aplikasi Anda:

   Groovy (build.gradle)

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

2. Konfigurasikan App Check untuk menggunakan factory penyedia debug di build debug Anda:

   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. Luncurkan aplikasi Anda di emulator atau perangkat debug. App Check akan mencetak token debug lokal ke output logcat Anda.
4. Salin dan daftarkan token debug ini di Firebase Console. Untuk mengetahui detail selengkapnya, lihat dokumentasi penyedia debug Firebase App Check.

Langkah 6: Pantau permintaan aplikasi dan tentukan penerapan

Catatan: Penerapan tidak benar-benar diperlukan agar laporan gangguan real-time dapat memanfaatkan verifikasi integritas perangkat; namun, perlindungan penuh terhadap penipuan tagihan, spoofing, dan penyalahgunaan kuota bergantung pada pengaktifan penerapan di tingkat project.

Sebelum mengaktifkan penerapan, pantau permintaan aplikasi Anda untuk memastikan bahwa Anda tidak akan mengganggu pengguna yang sah.

1. Buka layar metrik App Check di Firebase console untuk melihat persentase traffic yang diverifikasi dibandingkan dengan traffic yang tidak diverifikasi.
2. Setelah Anda yakin bahwa sebagian besar traffic Anda diverifikasi dan pengguna yang sah telah mengupdate ke versi aplikasi yang berisi implementasi App Check Anda, aktifkan penerapan.
3. Setelah penerapan diaktifkan, App Check akan menolak semua traffic tanpa token App Check yang valid.