Firebase Remote Config 使用入门

iOS+ Android Web Flutter Unity C++

重要提示：本部分介绍了在移动和 Web 客户端上配置 Remote Config 的步骤。对于服务器环境，请参阅在服务器环境中使用 Remote Config。

您可以使用 Firebase Remote Config 来定义应用中的参数并在云端更新它们的值。这样，您无需更新应用即可修改应用的外观和行为。本指南逐步介绍了入门步骤并提供了一些示例代码，所有这些代码都可以从 firebase/quickstart-ios GitHub 代码库中克隆或下载。

第 1 步：将 Remote Config 添加到您的应用

1. 将 Firebase 添加到您的 Apple 项目（如果尚未添加）。

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. 在参数标签页中，打开菜单，然后选择下载默认值。

   2. 看到提示时，启用 .plist (iOS)，然后点击下载文件。

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

由于这些更新后的参数值会影响应用的行为和外观，因此您应在提取后谨慎选择激活这些值的时机，以确保为用户提供流畅的体验，例如在用户下次打开您的应用时激活。如需更多信息和示例，请参阅 Remote Config 加载策略。

第 6 步：实时监听更新

提取参数值后，您可以使用实时 Remote Config 监听 Remote Config 后端中的更新。有更新可用时，实时 Remote Config 会向关联设备发送信号，并会在有新的 Remote Config 版本发布后自动提取更改内容。

适用于 Apple 平台的 Firebase SDK v10.7.0 及更高版本支持实时更新。

重要提示：实时 Remote Config 还需要 Firebase Remote Config Realtime API，系统应该已经为您启用了该 API。如需确认该 API 已启用，请打开 Google Cloud 控制台，选择您的项目，然后打开 API 和服务页面。该 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 v10.7.0+ 开始，您可以使用实时 Remote Config 在 Remote Config 后端中有更新的参数值发布后立即自动提取这些更新值，这意味着会绕过任何最小提取间隔设置。您可以使用实时更新，而无需频繁使用提取方法来刷新缓存。如需了解详情，请参阅实时监听更新。

在应用开发期间，您可能需要更频繁地提取以非常频繁地刷新缓存（每小时很多次），从而可以在开发和测试应用时进行快速迭代。在服务器上更新配置时，实时 Remote Config 更新会自动绕过缓存。为了让具有众多开发者的项目快速迭代，您可以在应用中临时添加一个具有较短最小提取间隔 (MinimumFetchInterval) 的 FIRRemoteConfigSettings 属性。

Remote Config 默认和建议的生产提取间隔为 12 小时，这意味着无论实际上调用了多少次提取方法，在 12 小时的时间段内最多从后端提取一次配置。具体而言，系统按以下顺序确定最小提取间隔：

1. fetch(long) 中的参数
2. FIRRemoteConfigSettings.MinimumFetchInterval 中的参数
3. 默认值 12 小时

请注意，此设置应仅用于开发，不要用于在生产环境中运行的应用。如果您只有一个小型的 10 人开发团队来测试应用，不大可能会达到服务端每小时配额上限。但如果您将应用推送给数千位测试用户，并将最小提取间隔设置为非常小的值，那么应用就可能会达到此配额上限。

后续步骤

浏览 Remote Config 使用场景并查看一些关键的概念和高级策略文档（如果您尚未这样做），包括：

• 管理 Remote Config 模板版本
• 配置加载策略