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 Android 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

    此外,在设置 Analytics(分析)时,您还需要将 Firebase SDK for Google Analytics 添加到应用中。

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.4"))
    
        // 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:21.6.3")
        implementation("com.google.firebase:firebase-analytics:21.5.1")
    }
    
    是否想要查找 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)

Java

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

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

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

第 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() {
                @Override
                public void onComplete(@NonNull Task 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 使用场景并查看一些关键的概念和高级策略文档(如果您尚未这样做),包括: