Menggunakan App Check untuk mengamankan Navigation SDK for iOS

Dukungan untuk App Check dengan Navigation SDK for iOS 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 App Attest. 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: Memantau permintaan aplikasi dan memutuskan penerapan).

Mengapa menggunakan App Check?

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

Navigasi

App Check membantu memblokir permintaan Navigation SDK for iOS utama dari sumber berbahaya atau tidak sah. Hal ini secara langsung menguntungkan Anda dengan melindungi project Anda 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 bergantung pada sinyal integritas perangkat dan aplikasi yang kuat.
• Cara App Check memvalidasi laporan: Laporan dan voting pengguna yang dikirim dari Navigation SDK for iOS menyertakan token App Check, yang digunakan oleh backend Google untuk memvalidasi legitimasi masukan, meningkatkan tingkat kepercayaan, dan memungkinkannya dievaluasi untuk dampak peta langsung.
• Dampak jika tidak menggunakan App Check: Laporan yang dikirimkan 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 iOS berjalan di perangkat yang tidak tepercaya, seperti ponsel yang di-root atau di-jailbreak. Untuk mendukung perangkat ini, 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, DeviceCheck atau App Attest, tunduk pada kuota dan batasan yang ditetapkan oleh Apple.
• Latensi Startup: Dalam sebagian besar situasi, pengguna tidak akan mengalami latensi selama penggunaan reguler, karena token App Check di-cache di perangkat. Sistem secara 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 yang aman, tetapi SDK secara 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 iOS versi 11.0 atau yang lebih baru terinstal.
• ID paket aplikasi.
• ID Tim Anda dari tab Membership di konsol Apple Developer.
• Jika Anda berencana menggunakan DeviceCheck, file kunci pribadi dan ID kunci Anda.
• Anda harus menjadi pemilik aplikasi di konsol Google Cloud.
• ID project aplikasi Anda dari konsol Google Cloud.

Langkah 1: Tambahkan Firebase ke aplikasi Anda

Ikuti petunjuk dalam dokumentasi developer Firebase untuk menambahkan Firebase ke aplikasi Anda. Tambahkan file GoogleService-Info.plist, tanpa diubah, ke tingkat root project Anda.

Di file AppDelegate, impor modul berikut:

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

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

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

Firebase memberikan petunjuk untuk setiap penyedia pengesahan default. Petunjuk ini menunjukkan cara menyiapkan project Firebase dan menambahkan library App Check ke aplikasi Anda. Ikuti contoh kode yang diberikan untuk melakukan inisialisasi App Check.

1. Ikuti petunjuk Firebase untuk menambahkan library App Check:
   • Petunjuk App Attest.
   • Petunjuk DeviceCheck.
2. Lakukan inisialisasi App Check di AppDelegate:
   • Jika Anda menggunakan App Attest, buat implementasi AppCheckProviderFactory dan daftarkan sebelum memanggil 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];

   • Jika Anda menggunakan DeviceCheck, tetapkan factory menggunakan kode berikut:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

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

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 mengimplementasikan dan mendaftarkan antarmuka penyedia token yang khusus untuk setiap SDK.

Buat file bernama AppCheckTokenProvider (atau, jika Anda menggunakan Objective-C, dua file bernama AppCheckTokenProvider.h dan AppCheckTokenProvider.m) di tingkat root aplikasi Anda.

Class ini harus mematuhi protokol GMSAppCheckTokenProvider dan mengimplementasikan metode 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

Langkah 4: Lakukan inisialisasi Navigation dan App Check API

Lakukan inisialisasi Navigation SDK for iOS (menggunakan GMSServices) dan daftarkan instance penyedia token Anda dengan mentransmisikan handle layanan buram bersama ke 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];

Langkah 5: Aktifkan proses debug (opsional)

Setelah App Check diterapkan untuk Navigation SDK for iOS, fitur aplikasi Anda yang bergantung pada Navigation SDK for iOS 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. Konfigurasikan factory penyedia debug di 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. Aktifkan logging di project Xcode Anda, luncurkan aplikasi, dan temukan token debug lokal di log konsol.
3. Salin dan tambahkan token debug ini ke Firebase Console. Untuk mengetahui detail selengkapnya, lihat dokumentasi penyedia debug Firebase App Check.

Langkah 6: Pantau permintaan aplikasi dan putuskan penerapan

Catatan: Penerapan tidak benar-benar diperlukan agar laporan gangguan real-time mendapatkan manfaat dari 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.