Firebase Remote Config 使用入门

iOS+ Android Web Flutter Unity C++

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

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

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

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

2. 使用 Remote Config 时，如需根据用户属性和目标设备来有条件地定位应用实例，则需要用到 Google Analytics。请务必在项目中启用 Google Analytics。

3. 在模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Remote Config 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

   此外，在设置 Analytics 时，您还需要将 Firebase SDK for Google Analytics 添加到应用中。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.6.0"))
   
       // Add the dependencies for the Remote Config and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config")
       implementation("com.google.firebase:firebase-analytics")
   }

   借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

   （替代方法） 在不使用 BoM 的情况下添加 Firebase 库依赖项

   如果您选择不使用 Firebase BoM，则必须在每个 Firebase 库的依赖项行中指定相应的库版本。

   请注意，如果您在应用中使用多个 Firebase 库，我们强烈建议您使用 BoM 来管理库版本，从而确保所有版本都兼容。

   dependencies {
       // Add the dependencies for the Remote Config and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config:22.0.1")
       implementation("com.google.firebase:firebase-analytics:22.1.2")
   }

   是否想要查找 Kotlin 专用的库模块？ 从 2023 年 10 月 (Firebase BoM 32.5.0) 开始，Kotlin 和 Java 开发者可以依赖于主库模块（如需了解详情，请参阅关于此计划的常见问题解答）。

注意：由于 Android SDK 依赖于 Remote Config REST API，因此切勿停用该 API（在典型的项目中，该 API 默认处于启用状态）。

第 2 步：获取 Remote Config 单例对象

获取 Remote Config 对象实例，并设置最小提取间隔以实现频繁刷新：

Kotlin+KTX

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
MainActivity.kt

Java

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
MainActivity.java

此单例对象用于存储应用内默认参数值，从后端中提取更新后的参数值，以及控制提取的值何时可供您的应用使用。

在开发期间，建议设置相对较短的最小提取间隔。如需了解详情，请参阅限制。

第 3 步：设置应用内默认参数值

您可以在 Remote Config 对象中设置应用内默认参数值，以便应用在连接到 Remote Config 后端之前能够按预期运行，并且保证在后端中未设置任何值时可以使用默认值。

重要提示：不要在 Remote Config 参数键或值中存储机密数据。Remote Config 数据在传输过程中会加密，但最终用户可以访问其客户端应用实例可用的任何默认或提取的 Remote Config 参数。

1. 使用 Map 对象或存储在您应用的 res/xml 文件夹中的 XML 资源文件指定一组参数名称和默认参数值。Remote Config 快速入门示例应用使用 XML 文件来指定默认参数名称和值。

   如果您已配置 Remote Config 后端参数值，则可以下载一个包含所有默认值的 XML 文件，并将其保存到应用的 res/xml 目录中：

   REST

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

   Firebase 控制台

   1. 在参数标签页中，打开菜单，然后选择下载默认值。

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

2. 使用 setDefaultsAsync(int) 将这些值添加到 Remote Config 对象，如下所示：

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

第 4 步：获取要在应用中使用的参数值

现在，您可以从 Remote Config 对象中获取参数值。如果您在后端中设置值，然后提取并激活它们，这些值便可供您的应用使用。否则，您将获得使用 setDefaultsAsync(int) 方法配置的应用内参数值。如需获取这些值，请调用下列与应用所需数据类型对应的方法，并传入参数键作为调用的实参：

• getBoolean()
• getDouble()
• getLong()
• getString()

第 5 步：在 Remote Config 后端中设置参数值

使用 Firebase 控制台或 Remote Config 后端 API，您可以创建新的服务器端默认值，这些值会根据您希望的条件逻辑或用户定位条件来替换应用内的值。本部分介绍了在 Firebase 控制台中创建这些值的步骤。

1. 在 Firebase 控制台中，打开您的项目。
2. 从菜单中选择 Remote Config，查看 Remote Config 信息中心。
3. 使用您在应用中指定的参数名称来定义参数。对于每个参数，您可以设置一个默认值（最终将替换应用内相应的默认值），也可以设置条件值。如需了解详情，请参阅 Remote Config 参数和条件。

第 6 步：提取并激活值

1. 如需从 Remote Config 后端提取参数值，请调用 fetch() 方法。系统将提取您在后端中设置的所有值，并将其存储在 Remote Config 对象中。

2. 如需将提取的参数值提供给您的应用，请调用 activate() 方法。

   如果您想在一次调用中提取并激活值，请使用 fetchAndActivate() 请求从 Remote Config 后端提取值，并使其可供应用使用：

   Kotlin+KTX

   remoteConfig.fetchAndActivate()
       .addOnCompleteListener(this) { task ->
           if (task.isSuccessful) {
               val updated = task.result
               Log.d(TAG, "Config params updated: $updated")
               Toast.makeText(
                   this,
                   "Fetch and activate succeeded",
                   Toast.LENGTH_SHORT,
               ).show()
           } else {
               Toast.makeText(
                   this,
                   "Fetch failed",
                   Toast.LENGTH_SHORT,
               ).show()
           }
           displayWelcomeMessage()
       }

   Java

   mFirebaseRemoteConfig.fetchAndActivate()
           .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   if (task.isSuccessful()) {
                       boolean updated = task.getResult();
                       Log.d(TAG, "Config params updated: " + updated);
                       Toast.makeText(MainActivity.this, "Fetch and activate succeeded",
                               Toast.LENGTH_SHORT).show();
   
                   } else {
                       Toast.makeText(MainActivity.this, "Fetch failed",
                               Toast.LENGTH_SHORT).show();
                   }
                   displayWelcomeMessage();
               }
           });

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

注意：如果您的应用不是使用 Gradle 构建的，您必须手动将正确的 google_app_id 字符串资源添加到应用，以使 Remote Config 可以进行初始化。google-services Gradle 插件通常会自动添加此资源，不过，您可以在 google-services.json 文件（从 Firebase 控制台下载）中找到相应的值。如需详细了解如何从 google-services.json 文件中获取 google_app_id 值，请参阅处理 JSON 文件。

第 7 步：实时监听更新

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

Firebase SDK for Android v21.3.0 及更高版本（Firebase BoM v31.2.4 及更高版本）支持实时更新。

重要提示：实时 Remote Config 还需要 Firebase Remote Config Realtime API，系统应该已经为您启用了该 API。如需确认该 API 已启用，请打开 Google Cloud 控制台，选择您的项目，然后打开 API 和服务页面。该 API 应显示为已启用。如果该 API 缺失或未启用，请点击启用 API 和服务，然后搜索 Firebase Remote Config Realtime API 并将其启用。

1. 在您的应用中，使用 addOnConfigUpdateListener() 开始监听更新并自动提取任何新参数值。此外，实现 onUpdate() 回调以激活更新的配置。

   Kotlin+KTX

   remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
       override fun onUpdate(configUpdate : ConfigUpdate) {
          Log.d(TAG, "Updated keys: " + configUpdate.updatedKeys);
   
          if (configUpdate.updatedKeys.contains("welcome_message")) {
              remoteConfig.activate().addOnCompleteListener {
                  displayWelcomeMessage()
              }
          }
       }
   
       override fun onError(error : FirebaseRemoteConfigException) {
           Log.w(TAG, "Config update error with code: " + error.code, error)
       }
   })

   Java

   mFirebaseRemoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
       @Override
       public void onUpdate(ConfigUpdate configUpdate) {
           Log.d(TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
           mFirebaseRemoteConfig.activate().addOnCompleteListener(new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   displayWelcomeMessage();
               }
           });
       }
       @Override
       public void onError(FirebaseRemoteConfigException error) {
           Log.w(TAG, "Config update error with code: " + error.getCode(), error);
       }
   });

2. 下次有新版本的 Remote Config 发布时，运行应用并监听更改的设备便会调用 ConfigUpdateListener。

限制

如果应用在短时间内执行提取的次数太多，则提取调用会受到限制，并且 SDK 会返回 FirebaseRemoteConfigFetchThrottledException。在 SDK 17.0.0 版本之前，应用在 60 分钟内最多可以发送 5 次提取请求（在较新版本中，此限制更为宽松）。

提示：从 Android SDK v21.3.0+ (Firebase BoM v31.3.0+) 开始，您可以使用实时 Remote Config 在 Remote Config 后端中有更新的参数值发布后立即自动提取这些更新值，这意味着会绕过任何最小提取间隔设置。如需了解详情，请参阅实时监听更新。

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

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

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

如需将最小提取间隔设为自定义值，请使用 FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)。

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

后续步骤

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

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