開始使用 Firebase 遠端設定

iOS+ Android 網頁版 Flutter Unity C++

重要事項： 本節說明如何設定 Remote Config 與行動和網頁用戶端。如需伺服器環境的相關資訊，請參閱「在伺服器環境中使用 Remote Config」一文。

您可以使用 Firebase Remote Config 在應用程式中定義參數，並在雲端更新參數值，藉此修改應用程式的外觀和行為，而無須發布應用程式更新。本指南將逐步引導您開始使用，並提供一些程式碼範例，您可以從 firebase/quickstart-ios GitHub 存放區複製或下載這些程式碼範例。

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

1. 如果您尚未將 Firebase 新增至 Apple 專案，請新增 Firebase。

2. 就 Remote Config 而言，您必須使用 Google Analytics，才能條件式指定應用程式執行個體的使用者屬性和目標對象。請確認您已在專案中啟用 Google Analytics。

3. 建立單例 Remote Config 物件，如以下範例所示：

   Swift

   remoteConfig = RemoteConfig.remoteConfig()
   let settings = RemoteConfigSettings()
   settings.minimumFetchInterval = 0
   remoteConfig.configSettings = settings
   ViewController.swift

   Objective-C

   self.remoteConfig = [FIRRemoteConfig remoteConfig];
   FIRRemoteConfigSettings *remoteConfigSettings = [[FIRRemoteConfigSettings alloc] init];
   remoteConfigSettings.minimumFetchInterval = 0;
   self.remoteConfig.configSettings = remoteConfigSettings;
   ViewController.m

這個物件可用於儲存應用程式內的預設參數值、從 Remote Config 後端擷取更新的參數值，以及控制擷取的值何時可供應用程式使用。

在開發期間，建議您將擷取間隔設為較低。詳情請參閱「節流」一節。

步驟 2：設定應用程式內的預設參數值

您可以在 Remote Config 物件中設定應用程式內的預設參數值，讓應用程式在連線至 Remote Config 後端之前能正常運作，並在後端未設定任何預設值時使用預設值。

重要事項： 請勿在 Remote Config 參數鍵或值中儲存機密資料。Remote Config 資料會在傳輸過程中加密，但使用者可以存取客戶端應用程式例項可用的任何預設或擷取的 Remote Config 參數。

1. 使用 NSDictionary 物件或 plist 檔案定義一組參數名稱和預設參數值。

   如果您已設定 Remote Config 後端參數值，可以下載產生的 plist 檔案，其中包含所有預設值，並將檔案儲存至 Xcode 專案。

   REST

   curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=PLIST -o RemoteConfigDefaults.plist
   

   Firebase 主控台

   1. 在「Parameters」分頁中，開啟 「Menu」，然後選取「Download default values」。

   2. 系統提示時，請啟用 iOS 專用的 .plist，然後按一下「下載檔案」。

2. 使用 setDefaults: 將這些值新增至 Remote Config 物件。以下範例會從 plist 檔案設定應用程式內的預設值：

   Swift

   remoteConfig.setDefaults(fromPlist: "RemoteConfigDefaults")
   ViewController.swift

   Objective-C

   [self.remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ViewController.m

注意： 這些程式碼片段參照範例 quickstart-ios 專案中的 RemoteConfigDefaults.plist 檔案。如果您使用下載的預設檔案，請使用 remote_config_defaults。

步驟 3：取得要在應用程式中使用的參數值

您現在可以從 Remote Config 物件取得參數值。如果您之後在 Remote Config 後端中設定值、擷取值，然後再啟用這些值，這些值就會提供給應用程式。否則，您會取得使用 setDefaults: 設定的應用程式內參數值。如要取得這些值，請呼叫 configValueForKey: 方法，並提供參數鍵做為引數。

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a parameter value using configValueForKey
let welcomeMessageValue = remoteConfig.configValue(forKey: "welcome_message")
let welcomeMessage = welcomeMessageValue.stringValue

let featureFlagValue = remoteConfig.configValue(forKey: "new_feature_flag")
let isFeatureEnabled = featureFlagValue.boolValue

在 Swift 中存取這些值的更易讀、更方便的方式，是透過 Swift 的下標記號：

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a string parameter value
let welcomeMessage = remoteConfig["welcome_message"].stringValue

// Retrieve a boolean parameter value
let isFeatureEnabled = remoteConfig["new_feature_flag"].boolValue

// Retrieve a number parameter value
let maxItemCount = remoteConfig["max_items"].numberValue.intValue

使用 Codable 進行類型安全設定

如果是較為複雜的設定，您可以使用 Swift 的 Codable 通訊協定，解碼 Remote Config 中的結構化資料。這可提供型別安全的設定管理機制，並簡化複雜物件的作業。

// Define a Codable struct for your configuration
struct AppFeatureConfig: Codable {
  let isNewFeatureEnabled: Bool
  let maxUploadSize: Int
  let themeColors: [String: String]
}

// Fetch and decode the configuration
func configureAppFeatures() {
  let remoteConfig = RemoteConfig.remoteConfig()
  remoteConfig.fetchAndActivate { status, error in
    guard error == nil else { return }

    do {
      let featureConfig = try remoteConfig["app_feature_config"].decoded(asType: AppFeatureConfig.self)
      configureApp(with: featureConfig)
    } catch {
      // Handle decoding errors
      print("Failed to decode configuration: \(error)")
    }
  }
}

這個方法可讓您：

• 定義複雜的設定結構。
• 自動剖析 JSON 設定。
• 存取 Remote Config 值時，請確保類型安全。
• 提供清晰易讀的程式碼，用於處理結構化 Remote Config 範本。

在 SwiftUI 中使用屬性包裝函式進行宣告式設定

屬性包裝函式是一項強大的 Swift 功能，可讓您在屬性宣告中加入自訂行為。在 SwiftUI 中，屬性包裝函式可用於管理狀態、繫結和其他屬性行為。詳情請參閱 Swift 語言指南。

struct ContentView: View {
  @RemoteConfigProperty(key: "cardColor", fallback: "#f05138")
  var cardColor

  var body: some View {
    VStack {
      Text("Dynamic Configuration")
        .background(Color(hex: cardColor))
    }
    .onAppear {
      RemoteConfig.remoteConfig().fetchAndActivate()
    }
  }
}

如要在 SwiftUI 中以宣告方式存取 Remote Config 值，並內建支援預設值和簡化設定管理，請使用 @RemoteConfigProperty 屬性包裝函式。

步驟 4：設定參數值

您可以使用 Firebase 控制台或 Remote Config 後端 API，根據所需的條件邏輯或使用者指定目標，建立新的後端預設值，覆寫應用程式內的值。本節將逐步說明如何在 Firebase 控制台中建立這些值。

1. 在 Firebase 控制台中開啟專案。
2. 選取選單中的 Remote Config，即可查看 Remote Config 資訊主頁。
3. 定義參數時，請使用與應用程式中定義的參數相同的名稱。您可以為每個參數設定預設值 (最終會覆寫應用程式內的預設值)，也可以設定條件值。詳情請參閱「Remote Config 參數和條件」。

4. 如果使用自訂信號條件，請定義屬性及其值。以下範例說明如何定義自訂信號條件。

   Swift

     Task {
         let customSignals: [String: CustomSignalValue?] = [
         "city": .string("Tokyo"),
         "preferred_event_category": .string("sports")
       ]
   
       do {
         try await remoteConfig.setCustomSignals(customSignals)
         print("Custom signals set successfully!")
         } catch {
             print("Error setting custom signals: \(error)")
         }
   }

   Objective-C

     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
       NSDictionary *customSignals = @{
         @"city": @"Tokyo",
         @"preferred_event_category": @"sports"
       };
   
       [self.remoteConfig setCustomSignals:customSignals withCompletion:^(NSError * _Nullable error) {
           if (error) {
               NSLog(@"Error setting custom signals: %@", error);
           } else {
               NSLog(@"Custom signals set successfully!");
           }
     }];
   });

步驟 5：擷取並啟用值

如要從 Remote Config 擷取參數值，請呼叫 fetchWithCompletionHandler: 或 fetchWithExpirationDuration:completionHandler: 方法。系統會擷取您在後端設定的所有值，並將這些值快取至 Remote Config 物件中。

如果您想在單一呼叫中擷取及啟用值，請使用 fetchAndActivateWithCompletionHandler:。

這個範例會從 Remote Config 後端擷取值 (非快取值)，並呼叫 activateWithCompletionHandler:，讓應用程式可使用這些值：

Swift

remoteConfig.fetch { (status, error) -> Void in
  if status == .success {
    print("Config fetched!")
    self.remoteConfig.activate { changed, error in
      // ...
    }
  } else {
    print("Config not fetched")
    print("Error: \(error?.localizedDescription ?? "No error available.")")
  }
  self.displayWelcome()
}
ViewController.swift

Objective-C

[self.remoteConfig fetchWithCompletionHandler:^(FIRRemoteConfigFetchStatus status, NSError *error) {
    if (status == FIRRemoteConfigFetchStatusSuccess) {
        NSLog(@"Config fetched!");
      [self.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
        if (error != nil) {
          NSLog(@"Activate error: %@", error.localizedDescription);
        } else {
          dispatch_async(dispatch_get_main_queue(), ^{
            [self displayWelcome];
          });
        }
      }];
    } else {
        NSLog(@"Config not fetched");
        NSLog(@"Error %@", error.localizedDescription);
    }
}];
ViewController.m

由於這些更新的參數值會影響應用程式的行為和外觀，因此您應在確保使用者享有順暢體驗的時間點啟用擷取的值，例如使用者下次開啟應用程式時。如需更多資訊和範例，請參閱「遠端設定載入策略」。

步驟 6：即時聆聽更新

擷取參數值後，您可以使用即時 Remote Config 來監聽 Remote Config 後端的更新。當有可用的更新時，即時 Remote Config 會向已連結的裝置發出信號，並在您發布新的 Remote Config 版本後自動擷取變更。

Apple 平台的 Firebase SDK 支援即時更新，版本為 10.7.0 以上。

重要事項：即時 Remote Config 也需要 Firebase Remote Config Realtime API，而您應該已啟用該 API。如要確認，請開啟 Google Cloud 控制台，選取專案，然後開啟「API 和服務」頁面。API 應顯示為已啟用。如果找不到或未啟用，請按一下「啟用 API 和服務」，搜尋「Firebase Remote Config Realtime API」，然後啟用。

1. 在應用程式中，呼叫 addOnConfigUpdateListener 即可開始聆聽更新，並自動擷取任何新的或更新的參數值。以下範例會監聽更新，並在呼叫 activateWithCompletionHandler 時，使用新擷取的值來顯示更新的歡迎訊息。

   Swift

   remoteConfig.addOnConfigUpdateListener { configUpdate, error in
     guard let configUpdate, error == nil else {
       print("Error listening for config updates: \(error)")
     }
   
     print("Updated keys: \(configUpdate.updatedKeys)")
   
     self.remoteConfig.activate { changed, error in
       guard error == nil else { return self.displayError(error) }
       DispatchQueue.main.async {
         self.displayWelcome()
       }
     }
   }

   Objective-C

   __weak __typeof__(self) weakSelf = self;
   [self.remoteConfig addOnConfigUpdateListener:^(FIRRemoteConfigUpdate * _Nonnull configUpdate, NSError * _Nullable error) {
     if (error != nil) {
       NSLog(@"Error listening for config updates %@", error.localizedDescription);
     } else {
       NSLog(@"Updated keys: %@", configUpdate.updatedKeys);
   
       __typeof__(self) strongSelf = weakSelf;
       [strongSelf.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
         if (error != nil) {
           NSLog(@"Activate error %@", error.localizedDescription);
         }
   
         dispatch_async(dispatch_get_main_queue(), ^{
           [strongSelf displayWelcome];
         });
       }];
     }
   }];

2. 下次發布新版 Remote Config 時，正在執行應用程式並監聽變更的裝置會呼叫完成處理常式。

調節

如果應用程式在短時間內擷取過多次，擷取呼叫會受到節流限制，SDK 會傳回 FIRRemoteConfigFetchStatusThrottled。在 SDK 6.3.0 之前，60 分鐘內的擷取要求上限為 5 次 (較新版本的限制較寬鬆)。

提示：從 Apple 平台 SDK 10.7.0 以上版本開始，您可以使用即時 Remote Config 自動擷取更新的參數值，並在 Remote Config 後端發布後立即擷取，無須設定擷取間隔。您可以使用即時更新，而非頻繁擷取快取資料來重新整理快取資料。詳情請參閱「即時接收更新」。

在應用程式開發期間，您可能會想更頻繁地擷取資料，以便快速重新整理快取 (每小時多次)，讓您在開發及測試應用程式時快速迭代。當設定在伺服器上更新時，即時遠端設定更新會自動略過快取。為了在有許多開發人員的專案中進行快速迭代，您可以在應用程式中暫時新增 FIRRemoteConfigSettings 屬性，並設定低的最低擷取間隔 (MinimumFetchInterval)。

Remote Config 的預設及建議的正式版擷取間隔為 12 小時，也就是說，無論實際發出多少擷取呼叫，在 12 小時的時間範圍內，系統不會從後端擷取多次設定。具體來說，最小擷取間隔會依照以下順序決定：

1. fetch(long) 中的參數
2. FIRRemoteConfigSettings.MinimumFetchInterval 中的參數
3. 預設值為 12 小時

請注意，這項設定僅供開發使用，不得用於正式版應用程式。如果您只是由 10 人的小型開發團隊測試應用程式，就不會達到每小時服務端配額限制。不過，如果您將應用程式推送給數千名測試使用者，且擷取間隔時間極短，應用程式就可能會達到這個配額。

後續步驟

如果您尚未探索，請參閱 Remote Config 用途，並查看一些重要概念和進階策略說明文件，包括：

• 管理 Remote Config 範本版本
• 設定載入策略