使用 App Check 保護 Navigation SDK for iOS

Firebase App Check 會封鎖來自非正當應用程式的流量，保護應用程式對 Google Maps Platform 的呼叫。方法是向 App Attest 等認證供應商要求評估應用程式或裝置的真實性。將應用程式與 App Check 整合，即可防範惡意和未經授權的要求，進而避免帳單出現未授權扣款。App Check 也能大幅改善車隊應用程式生態系統中的即時中斷回報功能，讓所有使用應用程式的司機受惠。詳情請參閱「中斷回報」。

為什麼要使用 App Check？

App Check 可保護 Navigation SDK for iOS 的兩個不同部分：主要導航功能和中斷回報。

App Check 可協助封鎖來自惡意或未授權來源的主要 Navigation SDK for iOS 要求。這項措施可直接保護您的專案，避免帳單詐欺和配額用盡。

服務中斷回報

如果應用程式支援即時回報服務中斷和投票功能，強烈建議使用 App Check。啟用 App Check 可確保駕駛人取得最準確的路線，並考量所有即時回饋。

App Check 對報表的重要性：

  • 封閉道路的信任門檻較高：道路封閉等影響路線的事件，可能會大幅改變所有駕駛人的路線行為。為避免地圖遭到破壞、出現垃圾內容或不實回報，Google 的道路封閉中斷審查基礎架構會依賴強大的裝置和應用程式完整性信號。
  • App Check 如何驗證回報：從 Navigation SDK for iOS 傳送的使用者回報和投票包含 App Check 權杖，Google 後端會使用該權杖驗證意見回饋的合法性，提高其信任等級，並評估對線上地圖的影響。
  • 不使用 App Check 的影響：如果提交的報表不含有效的 App Check 權杖，系統會以較低信任度的模型評估，且可能只會當做靜默信號處理。也就是說，雖然使用者仍可回報和投票，但回報內容較不可能顯示在地圖上，或影響其他駕駛人的路線，且需要額外驗證。

App Check 適合我嗎？

在大多數情況下，我們建議使用 App Check。不過，在下列情況下，您不需要或不支援 App Check：

  • 私人或實驗性應用程式：如果應用程式不開放公眾存取，就不需要 App Check。
  • 遭駭裝置：建議的認證供應商會防止 Navigation SDK for iOS 在不可信任的裝置上執行，例如已啟用 Root 權限或越獄解鎖的手機。如要支援這些裝置，請部署自訂認證供應商。

導入步驟總覽

概括來說，您需要按照下列步驟，將應用程式與 App Check 整合：

  1. 將 Firebase 新增至應用程式。
  2. 新增 App Check 程式庫並初始化 App Check。
  3. 新增權杖供應商。這個步驟會叫用您選擇的認證供應商，驗證裝置或應用程式的完整性。
  4. 初始化 Navigation 和 App Check API。
  5. 啟用偵錯功能。這在開發或持續整合 (CI) 環境中非常實用。
  6. 啟用強制執行前，請先監控應用程式要求。這樣一來，您就能順利強制執行 App Check，不會干擾使用者。

規劃 App Check 整合時的注意事項

  • 認證供應商配額：我們推薦的認證供應商 DeviceCheck 或 App Attest，須遵守 Apple 設定的配額和限制。
  • 啟動延遲：在多數情況下，使用者在正常使用時不會遇到延遲，因為 App Check 權杖會快取在裝置上。系統會在 App Check 權杖到期前，自動在背景重新整理權杖，確保效能不受影響。不過，如果沒有有效的 App Check 權杖，應用程式使用者在啟動時會遇到一些延遲。舉例來說，如果快取的權杖過期或遺失，冷啟動期間就會發生這種延遲。
  • 權杖存留時間 (TTL)：存留時間 (TTL) 決定 App Check 權杖在需要重新整理前的有效時間。您可以在 Firebase 控制台中，將這段時間設為 30 分鐘到 7 天。建議將時間長度設為 1 小時，做為安全基準，但 SDK 會自動在 TTL 時間長度約一半時，嘗試在背景重新整理。如需管理中心逐步操作說明，請參閱 Firebase App Check 說明文件。

將應用程式與 App Check 整合

必要條件和規定

  • 應用程式已安裝 Navigation SDK for iOS 11.0 以上版本。
  • 應用程式的軟體包 ID。
  • Apple Developer 控制台「Membership」分頁中的團隊 ID。
  • 如果打算使用 DeviceCheck，請提供私密金鑰檔案和金鑰 ID。
  • 您必須是 Google Cloud 控制台中的應用程式擁有者。
  • 應用程式在 Google Cloud 控制台中的專案 ID。

步驟 1：將 Firebase 新增至應用程式

按照 Firebase 開發人員說明文件中的指示，將 Firebase 新增至應用程式。將 GoogleService-Info.plist 檔案新增至專案的根層級，不需修改。

在 AppDelegate 檔案中，匯入下列模組：

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

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

步驟 2：新增 App Check 程式庫並初始化 App Check

Firebase 會提供每個預設認證供應商的操作說明。這些操作說明會引導您設定 Firebase 專案，並將 App Check 程式庫新增至應用程式。請按照提供的程式碼範例初始化 App Check。

  1. 按照 Firebase 操作說明新增 App Check 程式庫：
  2. 在 AppDelegate 中初始化 App Check：
    • 如果您使用 App Attest，請先建立 AppCheckProviderFactory 的實作並註冊，再呼叫 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];
    • 如果改用 DeviceCheck，請使用下列指令設定工廠：

      Swift

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      Objective-C

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

步驟 3：新增權杖供應商

在應用程式的根層級建立名為 AppCheckTokenProvider 的檔案 (如果使用 Objective-C，則建立名為 AppCheckTokenProvider.h 和 AppCheckTokenProvider.m 的兩個檔案)。

這個類別必須符合 GMSAppCheckTokenProvider 通訊協定，並實作 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

步驟 4：初始化 Navigation 和 App Check API

初始化 Navigation SDK for iOS，並在 GMSServices 上註冊權杖提供者執行個體：

Swift

// In application(_:didFinishLaunchingWithOptions:)
GMSServices.provideAPIKey("YOUR_API_KEY")

// Register your App Check token provider before initializing Navigation SDK for iOS
GMSServices.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.appCheckTokenProvider = [[AppCheckTokenProvider alloc] init];

步驟 5：啟用偵錯功能 (選用)

Navigation SDK for iOS 強制執行 App Check 後，應用程式中依賴 Navigation SDK for iOS 的功能，將無法在模擬器或持續整合 (CI) 環境中執行，因為這些環境不符合有效裝置的條件。如要在開發和測試期間於這些環境中執行應用程式，您必須建立應用程式的偵錯版本，並使用 App Check 偵錯服務，而非正式版認證服務。

  1. 在 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. 在 Xcode 專案中啟用記錄功能，啟動應用程式，然後在控制台記錄中找出本機偵錯權杖。
  3. 複製這個偵錯權杖，並新增至 Firebase 控制台。詳情請參閱 Firebase App Check 偵錯服務說明文件。

步驟 6：監控應用程式要求並決定是否強制執行

啟用強制執行前，請先監控應用程式要求，確保不會干擾合法使用者。

  1. 前往 Firebase 控制台的 App Check 指標畫面，查看已驗證和未驗證流量的百分比。
  2. 確認大部分流量都已通過驗證，且合法使用者已更新至包含 App Check 實作的應用程式版本後，即可啟用強制執行。
  3. 強制執行後，App Check 會拒絕所有不具備有效 App Check 權杖的流量。