Pilih platform: Android iOS JavaScript

Menggunakan App Check untuk mengamankan kunci API Anda

Firebase App Check memberikan perlindungan untuk panggilan dari aplikasi Anda ke Google Maps Platform dengan memblokir traffic yang berasal dari sumber selain aplikasi yang sah. Hal ini dilakukan dengan memeriksa token dari penyedia pengesahan seperti App Attest. Mengintegrasikan aplikasi Anda dengan App Check membantu melindungi dari permintaan berbahaya, sehingga Anda tidak ditagih untuk panggilan API yang tidak sah.

Apakah App Check cocok untuk saya?

App Check direkomendasikan dalam sebagian besar kasus, tetapi App Check tidak diperlukan atau tidak didukung dalam kasus berikut:

  • Anda menggunakan Places SDK asli. App Check hanya didukung untuk Places SDK (Baru).
  • Aplikasi pribadi atau eksperimental. Jika aplikasi Anda tidak dapat diakses secara publik, App Check tidak diperlukan.
  • Jika aplikasi Anda hanya digunakan server-ke-server, App Check tidak diperlukan. Namun, jika server yang berkomunikasi dengan GMP digunakan oleh klien publik (seperti aplikasi seluler), pertimbangkan untuk menggunakan App Check untuk melindungi server tersebut, bukan GMP.
  • Penyedia pengesahan yang direkomendasikan App Check tidak akan berfungsi di perangkat yang dianggap terkompromi atau tidak tepercaya oleh penyedia pengesahan Anda. Jika Anda perlu mendukung perangkat tersebut, Anda dapat men-deploy layanan pengesahan kustom. Untuk mengetahui informasi selengkapnya, lihat petunjuk.

Ringkasan langkah-langkah penerapan

Secara umum, berikut adalah langkah-langkah yang akan Anda ikuti untuk mengintegrasikan aplikasi dengan App Check:

  1. Tambahkan Firebase ke aplikasi Anda.
  2. Tambahkan dan lakukan inisialisasi library App Check.
  3. Tambahkan penyedia token ke aplikasi Anda.
  4. Lakukan inisialisasi Places API dan App Check API.
  5. Aktifkan proses debug.
  6. Pantau permintaan aplikasi Anda dan tentukan penegakan.

Setelah terintegrasi dengan App Check, Anda dapat melihat metrik traffic backend di Firebase console. Metrik ini memberikan perincian permintaan berdasarkan apakah permintaan tersebut disertai dengan token App Check yang valid. Lihat dokumentasi Firebase App Check untuk mengetahui informasi selengkapnya.

Jika Anda yakin bahwa sebagian besar permintaan berasal dari sumber yang sah dan pengguna telah mengupdate ke aplikasi versi terbaru yang menyertakan penerapan App Check, Anda dapat mengaktifkan penegakan. Setelah penerapan diaktifkan, App Check akan menolak semua traffic tanpa token App Check yang valid.

Pertimbangan saat merencanakan integrasi App Check

Berikut beberapa hal yang perlu dipertimbangkan saat Anda merencanakan integrasi:

  • Penyedia pengesahan yang kami rekomendasikan, DeviceCheck atau App Attest, tunduk pada kuota dan batasan yang ditetapkan oleh Apple.

    Anda dapat memilih untuk menggunakan penyedia pengesahan kustom, meskipun ini adalah kasus penggunaan lanjutan. Lihat dokumentasi Firebase App Check untuk mengetahui informasi selengkapnya.

  • Pengguna aplikasi Anda akan mengalami beberapa latensi saat aplikasi dimulai. Namun, setelahnya, pengesahan ulang berkala akan terjadi di latar belakang dan pengguna tidak akan lagi mengalami latensi. Jumlah latensi yang tepat saat startup bergantung pada penyedia pengesahan yang Anda pilih.

    Jumlah waktu validitas token App Check (time to live, atau TTL) menentukan frekuensi pengesahan ulang. Durasi ini dapat dikonfigurasi di Firebase console. Pengesahan ulang terjadi saat sekitar setengah TTL telah berlalu. Untuk mengetahui informasi selengkapnya, lihat dokumen Firebase untuk penyedia pengesahan Anda.

Mengintegrasikan aplikasi Anda dengan App Check

Prasyarat dan persyaratan

  • Aplikasi dengan Places SDK versi 9.2 atau yang lebih baru terinstal.
  • ID paket aplikasi.
  • ID Tim Anda dari Apple Member Center, di bagian Membership.
  • Jika Anda berencana menggunakan Device Check, file kunci pribadi dan ID kunci Anda.
  • Anda harus menjadi pemilik aplikasi di Konsol Cloud.
  • Anda akan memerlukan project ID aplikasi dari Konsol Cloud

Langkah 1: Menambahkan Firebase ke aplikasi Anda

Ikuti petunjuk dalam dokumentasi developer Firebase untuk menambahkan Firebase ke aplikasi Anda.

Saat mendaftarkan aplikasi, Anda akan mendapatkan file konfigurasi, GoogleService-Info.plist. Tambahkan file ini, tanpa diubah, ke tingkat root aplikasi Anda.

Places Swift SDK for iOS

import FirebaseCore
import FirebaseAppCheck
import GooglePlacesSwift

Swift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

Objective-C

@import FirebaseCore;      
@import FirebaseAppCheck;
@import GooglePlaces;

Langkah 2: Tambahkan library App Check dan 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 menginisialisasi App Check.

  1. Ikuti petunjuk Firebase untuk menambahkan library App Check:
  2. Lakukan inisialisasi App Check.
    • Jika Anda menggunakan App Attest, ikuti dokumentasi developer Firebase untuk App Attest..

      Ikuti petunjuk Firebase App Check untuk membuat penerapan AppCheckProviderFactory dan menambahkannya ke file AppDelegate Anda.

      Places Swift SDK for iOS

      let providerFactory = YourAppCheckProviderFactory()
AppCheck.setAppCheckProviderFactory(providerFactory)

      Swift

      let providerFactory = YourAppCheckProviderFactory()
AppCheck.setAppCheckProviderFactory(providerFactory)

      Objective-C

      YourAppCheckProviderFactory *providerFactory =
    [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
    • Jika Anda menggunakan Pemeriksaan Perangkat, tambahkan kode berikut ke AppDelegate Anda:

      Places Swift SDK for iOS

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      Swift

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      Objective-C

      [FIRAppCheck setAppCheckProviderFactory:providerFactory];

Langkah 3: Tambahkan penyedia token

Buat file bernama AppCheckTokenProvider (atau, jika Anda menggunakan Objective-C, dua file bernama AppCheckTokenProvider.h dan AppCheckTokenProvider.m) di tingkat root aplikasi Anda. Tambahkan pernyataan impor dan definisi class berikut:

Places Swift SDK for iOS

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlacesSwift
      
struct TokenProvider: AppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}

Swift

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlaces

class AppCheckTokenProvider: NSObject, GMSPlacesAppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}

Objective-C

// AppCheckTokenProvider.h

@import Foundation;
@import GooglePlaces;

@interface AppCheckTokenProvider : NSObject <GMSPlacesAppCheckTokenProvider>
@end

// AppCheckTokenProvider.m

#import "AppCheckTokenProvider.h"

@import FirebaseAppCheck;

@implementation AppCheckTokenProvider

- (void)fetchAppCheckTokenWithCompletion:(nonnull GMSAppCheckTokenCompletion)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 Places API dan App Check API

  1. Dalam file AppDelegate, lakukan inisialisasi Places API:

    Places Swift SDK for iOS

    PlacesClient.provideAPIKey("YOUR_API_KEY")

    Swift

    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

    Objective-C

    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
  2. Kemudian, lakukan inisialisasi App Check API:

    Places Swift SDK for iOS

    PlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

    Swift

    GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

    Objective-C

    [GMSPlacesClient setAppCheckTokenProvider:[[AppCheckTokenProvider alloc] init]];

Langkah 5: Aktifkan proses debug (opsional)

Jika ingin mengembangkan dan menguji aplikasi secara lokal, atau menjalankannya di lingkungan continuous integration (CI), Anda dapat membuat build debug aplikasi yang menggunakan secret debug untuk mendapatkan token App Check yang valid. Hal ini memungkinkan Anda menghindari penggunaan penyedia pengesahan nyata dalam build debug.

Untuk menguji aplikasi Anda di Simulator atau di perangkat pengujian:

  • Buat dan tetapkan factory penyedia debug App Check.

    Contoh kode ini menangani skenario debug dan produksi:

    Places Swift SDK for iOS

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

    Swift

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

    Objective-C

    if (targetEnvironment == simulator){

FIRAppCheckDebugProviderFactory *providerFactory =
      [[FIRAppCheckDebugProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}

else {

YourAppCheckProviderFactory *providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}
  • Aktifkan logging di project Xcode Anda, luncurkan aplikasi, dan temukan token debug lokal di log.
  • Tambahkan token ini ke Firebase console.
  • Untuk mengetahui informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Untuk menjalankan aplikasi Anda di lingkungan CI:

  • Buat token debug di Firebase console dan tambahkan ke penyimpanan kunci aman sistem CI Anda.
  • Di Xcode, tambahkan variabel lingkungan ke skema pengujian Anda dengan nama FIRAAppCheckDebugToken dan $(APP_CHECK_DEBUG_TOKEN) (atau yang serupa) sebagai nilainya.
  • Di skrip pengujian CI Anda, teruskan token debug sebagai variabel lingkungan.

  • Buat dan tetapkan factory penyedia debug App Check.

    Contoh kode ini menangani skenario debug dan produksi:

    Places Swift SDK for iOS

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

    Swift

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

    Objective-C

    #if DEBUG
id<FIRAppCheckProviderFactory> providerFactory =
    [[FIRAppCheckDebugProviderFactory alloc] init];
#else  // DEBUG
id<FIRAppCheckProviderFactory> providerFactory =
    [[YourAppCheckProviderFactory alloc] init];
#endif  // DEBUG
AppCheck.setAppCheckProviderFactory(providerFactory)
  • Untuk mengetahui informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Langkah 6: Pantau permintaan aplikasi Anda dan tentukan penegakan

Sebelum memulai penerapan, Anda harus memastikan bahwa pengguna sah aplikasi Anda tidak akan terganggu. Untuk melakukannya, buka layar metrik App Check untuk melihat persentase traffic aplikasi Anda yang diverifikasi, sudah tidak berlaku, atau tidak sah. Setelah melihat bahwa sebagian besar traffic Anda diverifikasi, Anda dapat mengaktifkan penerapan.

Lihat dokumentasi Firebase App Check untuk mengetahui informasi dan petunjuk selengkapnya.