Firebase 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 开发者可以依赖于主库模块（如需了解详情，请参阅关于此计划的常见问题解答）。

第 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 后端之前能够按预期运行，并且保证在后端中未设置任何值时可以使用默认值。

  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) 方法配置的应用内参数值。如需获取这些值，请调用下列与应用所需数据类型对应的方法，并传入参数键作为调用的实参：

第 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 加载策略。

第 7 步：实时监听更新

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

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

  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 次提取请求（在较新版本中，此限制更为宽松）。

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

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

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

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

后续步骤

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