“在 Android 上集成 Remote Config”Codelab

1. 简介

上次更新日期：2021 年 3 月 9 日

什么是 Firebase Remote Config？

Firebase Remote Config 是一项云服务，可让您更改应用的行为和外观，而无需用户下载应用更新，并且完全免费。使用 Remote Config 时，您可以创建应用内默认值以控制应用的行为和外观。之后，您便可以使用 Firebase 控制台或 Remote Config 后端 API 为所有应用用户或细分用户群替换应用内默认值。您的应用可控制何时应用更新，并能经常检查有无更新并应用更新，且对性能的影响微乎其微。

运作方式

Remote Config 包括一个客户端库，可以处理如提取和缓存参数值等重要任务，同时仍让您能够控制何时激活新的值，从而左右应用用户的体验。这样，您就可以通过控制更改的时机来维持良好的应用体验。

Remote Config 客户端库中的各种 get 方法提供了统一的参数值访问点。应用在获取服务器端值时所使用的逻辑与在获取应用内默认值时相同，因此您无需编写大量代码，就可以将 Remote Config 的各项功能添加到您的应用中。

如需替换应用内默认值，您可以使用 Firebase 控制台或 Remote Config 后端 API 来创建与应用中所用参数同名的参数。对于每个参数，您可以设置服务器端默认值来替换应用内默认值，也可以创建条件值来替换满足特定条件的应用实例的应用内默认值。下图展示了参数值在 Remote Config 后端和应用中的优先级排序：

学习内容

如何实现 Firebase Remote Config
如何使用 Firebase Remote Config 在不更新应用的情况下更改值

所需条件

最新版本的 Android Studio
Firebase 账号
（建议使用，但非必需）用于运行应用的 Android 实体设备
具备 Java 或 Kotlin 基础知识

2. 准备工作

（可选）下载示例代码

在此 Codelab 中，您将构建自己的测试应用，但如果您想查看并运行现有的示例应用，可以下载快速入门示例代码。

点击以下按钮可下载本 Codelab 的所有代码：

解压下载的 ZIP 文件。此操作将解压缩名为 quickstart-android-master 的根文件夹。

…或从命令行克隆 GitHub 代码库。

$ git clone https://github.com/firebase/quickstart-android.git

代码库包含多个文件夹。我们将使用 config 文件夹。

（可选）导入示例代码

启动 Android Studio，然后在欢迎界面中选择“导入项目”。然后打开下载的文件夹，选择 config 文件夹。然后点击“打开”。

创建新的 Android 项目

在 Android Studio 中，启动新项目
选择基本活动
在“配置项目”界面中：
为您的项目命名。系统会自动为您生成软件包名称和保存位置。
语言：Java
最低 SDK 版本为 16

3. 将 Firebase 和 Firebase Analytics 添加到您的 Android 项目

创建 Firebase 项目

您必须先创建一个要关联到您的 Android 应用的 Firebase 项目，然后才能将 Firebase 添加到该 Android 应用。请访问了解 Firebase 项目以了解详情。

在 Firebase 控制台中，点击添加项目，然后选择或输入一个项目名称。

如果您已有 Google Cloud Platform (GCP) 项目，则可以从下拉菜单中选择该项目，然后将 Firebase 资源添加到该项目中。

（可选）如果要创建一个新项目，可以修改项目 ID。

Firebase 会自动为您的 Firebase 项目分配一个唯一的 ID。如需详细了解 Firebase 如何使用项目 ID，请访问“了解 Firebase 项目”。

点击继续。
为您的项目设置 Google Analytics，以便在使用以下任何 Firebase 产品时获得最佳体验：

Firebase Crashlytics
Firebase Predictions
Firebase Cloud Messaging
Firebase In-App Messaging
Firebase Remote Config
Firebase A/B Testing

出现提示时，选择使用现有的 Google Analytics 账号或新建账号。如果您选择新建账号，请选择 Analytics 报告位置，然后接受项目的数据共享设置和 Google Analytics 条款。

点击创建项目（如果使用现有的 GCP 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中 Firebase 项目的概览页面。

在 Firebase 中注册应用

创建 Firebase 项目后，您就可以向其中添加 Android 应用了。

请访问了解 Firebase 项目，详细了解将应用添加到 Firebase 项目的最佳做法和注意事项，包括如何处理多个 build 变体。

转到 Firebase 控制台。
在项目概览页面顶部，点击 Android 图标以启动设置工作流。如果您已向 Firebase 项目添加了应用，请点击“添加应用”以显示平台选项。
在 Android 软件包名称字段中输入应用的软件包名称。
（可选）输入应用别名。
将 SHA-1 字段留空，因为此项目不需要 SHA-1。
点击注册应用。

添加 Firebase 配置文件

接下来，系统会提示您下载一个包含应用所需的所有 Firebase 元数据的配置文件。点击下载 google-services.json 以获取 Firebase Android 配置文件 (google-services.json)。

在项目级 Gradle 文件 (build.gradle) 中添加规则，以纳入 Google 服务 Gradle 插件。此外，请确认您拥有 Google 的 Maven 制品库。

项目级 build.gradle (`<project>/build.gradle`)：

buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

在您的模块（应用级）Gradle 文件（通常是 app/build.gradle）中，应用 Google 服务 Gradle 插件：

应用级 build.gradle (`<project>/<app-module>/build.gradle`)：

apply plugin: ‘com.android.application'

// 添加以下行：

apply plugin: ‘com.google.gms.google-services' // Google 服务插件

android {

// ...

}

将 Firebase SDK 添加到您的 Android 应用

对于 Remote Config，您需要使用 Google Analytics 才能根据用户属性和受众群体对应用实例进行条件定位。请确保在项目中启用 Google Analytics。

（示例快速入门代码中已完成此操作）

使用 Firebase Android BoM 在模块（应用级）Gradle 文件（通常为 app/build.gradle）中声明 Remote Config Android 库的依赖项。借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

此外，在设置 Analytics 时，您还需要将适用于 Google Analytics 的 Firebase SDK 添加到您的应用中。在“dependencies”下，添加以下代码：

app/build.gradle

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:26.6.0')

    // Declare 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'
}

将您的项目与 Gradle 文件同步

为确保您的应用拥有所有依赖项，请依次选择 File > Sync Project with Gradle Files，将项目与 Gradle 文件同步。

4. 查看 Remote Config 的主要组件

现在，我们将回顾在应用中使用 Remote Config 的步骤。这些步骤已在快速入门 Codelab 代码中完成。请在查看快速入门 Codelab 代码时使用本部分，以了解代码执行的相关操作。

1. 获取 Remote Config 单例对象

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

MainActivity.java

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

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

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

2. 设置应用内默认参数值

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

您可以使用 Map 对象或存储在应用 res/xml 文件夹中的 XML 资源文件定义一组参数名称和默认参数值。Remote Config 快速入门示例应用使用 XML 文件来指定默认参数名称和值。您可以按以下方式创建自己的 XML 文件：

在 res 文件夹下创建 xml 文件夹。

右键点击新创建的 xml 文件夹，然后创建一个文件。

设置默认值。在下一部分中，您将尝试更改 Remote Config 快速入门 XML 文件中的默认值。
使用 setDefaultsAsync(int) 方法将这些值添加到 Remote Config 对象，如下所示：

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. 获取要在应用中使用的参数值

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

4. 提取并激活值

如需从 Remote Config 后端提取参数值，请调用 fetch() 方法。系统将提取您在后端中设置的所有值，并将其存储在 Remote Config 对象中。
如需让应用可以使用所提取的参数值，请调用 activate() 方法。如果需要在同一次调用中提取和激活值，则可以使用 fetchAndActivate() 请求，从 Remote Config 后端提取值，并使其可供应用使用：

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

节流

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

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

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

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

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

5. 使用 Remote Config 更改应用行为

更改应用内默认参数

打开 res/xml/remote_config_defaults.xml 并将默认值更改为其他值。

res/xml/remote_config_defaults.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- START xml_defaults -->
<defaultsMap>
    <entry>
        <key>loading_phrase</key>
        <value>Fetching config...</value>
    </entry>
    <entry>
        <key>welcome_message_caps</key>
        <value>false</value>
    </entry>
    <entry>
        <key>welcome_message</key>
        <value>Welcome to my awesome app!</value>
    </entry>
</defaultsMap>
    <!-- END xml_defaults -->

验证应用内默认值更改

在模拟器中或使用测试设备运行项目，以确认行为。
点击 Java 或 Kotlin 版本中的“打开”。

查看主视图中的欢迎辞。

在 Remote Config 后端中设置参数值

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

打开 Firebase 控制台，然后打开您的项目。
从“互动”部分的左侧菜单中选择 Remote Config，以查看 Remote Config 信息中心。
在 Add a parameter 下，输入 Parameter key. 在 Default value 下，添加所需的任何文本。然后点击“添加参数”。在此 Codelab 中，我们将使用 res/xml/remote_config_defaults.xml 文件中的参数键。如需了解详情，请参阅下表：

参数键	默认值 (`remote_config_defaults.xml`)	说明
loading_phrase	正在提取配置…	字符串；在提取 Remote Config 值时显示。
welcome_message_caps	false	布尔值；如果为 true，则将 welcome_message 更改为全大写
welcome_message	欢迎使用我的精彩应用！	字符串；欢迎辞

示例屏幕截图：

添加完参数后，点击“发布更改”。
在模拟器或设备上再次运行应用，这次点击“Fetch Remote Welcome”按钮。

欢迎消息应根据您的 Remote Config 参数和值进行更新！

6. 恭喜

恭喜！您已成功使用 Remote Config 更改了欢迎消息！您还可以通过许多其他方式利用 Remote Config 来更改和自定义应用。请参阅以下其他资源：

“在 Android 上集成 Remote Config”Codelab

1. 简介

什么是 Firebase Remote Config？

运作方式

学习内容

所需条件

2. 准备工作

（可选）下载示例代码

（可选）导入示例代码

创建新的 Android 项目

3. 将 Firebase 和 Firebase Analytics 添加到您的 Android 项目

创建 Firebase 项目

在 Firebase 中注册应用

添加 Firebase 配置文件

项目级 build.gradle (<project>/build.gradle)：

应用级 build.gradle (<project>/<app-module>/build.gradle)：

将 Firebase SDK 添加到您的 Android 应用

app/build.gradle

将您的项目与 Gradle 文件同步

4. 查看 Remote Config 的主要组件

1. 获取 Remote Config 单例对象

MainActivity.java

2. 设置应用内默认参数值

MainActivity.java

3. 获取要在应用中使用的参数值

4. 提取并激活值

MainActivity.java

节流

5. 使用 Remote Config 更改应用行为

更改应用内默认参数

验证应用内默认值更改

在 Remote Config 后端中设置参数值

6. 恭喜

项目级 build.gradle (`<project>/build.gradle`)：

应用级 build.gradle (`<project>/<app-module>/build.gradle`)：