Remote Config 参数和条件

客户端模板 服务器模板

您可以为客户端和服务器用例配置模板。客户端模板可提供给所有实现了适用于 Remote Config 的 Firebase 客户端 SDK 的应用实例使用，包括 Android、Apple、Web、Unity、Flutter 和 C++ 应用。服务器专属 Remote Config 模板中的参数和值可提供给使用 Firebase Admin Node.js SDK 12.1.0 版或更高版本的 Remote Config 实现（包括 Cloud Run 和 Cloud Functions）使用。

使用 Firebase 控制台或 Remote Config 后端 API 时，您需要定义一个或多个参数（键值对），并为这些参数提供应用内默认值。您可以通过定义参数值来替换应用内默认值。参数键和参数值都是字符串，不过，当您在自己的应用中使用参数值时，这些值可以转换为其他数据类型。

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

借助 Firebase 控制台、Admin SDK 或 Remote Config REST API，您可以为参数创建新的默认值，以及用于定位应用实例组的条件值。每当您在 Firebase 控制台中更新配置时，Firebase 都会创建并发布 Remote Config 模板的新版本。系统会存储以前的版本，便于您根据需要进行检索或回滚。您可以通过 Firebase 控制台、Firebase Admin SDK 和 REST API 来执行相关操作；如需了解详情，请参阅管理 Remote Config 模板版本。

本指南将介绍参数、条件、规则、条件值，以及各种参数值在 Remote Config 后端和应用中的优先级，另外还详细说明了用于创建条件的规则类型。

条件、规则和条件值

条件用于定位一组应用实例。条件由一条或多条规则组成，对于给定应用实例，这些规则必须全部求值为 true，才能使条件求值为 true。如果规则的值未指定（例如没有值可用），该规则将求值为 false。

例如，指定应用的初始屏幕的参数可以使用规则 if device_os = Android，根据操作系统类型显示不同的图片：

或者，可以使用时间条件来控制应用何时显示特别促销商品。

一个参数可以具有多个使用不同条件的条件值，并且多个参数可以共用一个项目中的多个条件。在 Firebase 控制台的“参数”标签页中，您可以查看每个参数的条件值的提取百分比。此指标表示过去 24 小时内收到每个值的请求所占的百分比。

参数值优先级

一个参数可能有多个与其关联的条件值。以下规则用于确定在某个特定时间点从 Remote Config 模板提取哪个值，以及在给定的应用实例中使用哪个值：

1. 首先，对于某个给定的客户端请求，如果有任何条件求值为 true，则采用相应的条件值。如果多个条件求值为 true，则 Firebase 控制台界面中显示的第一个（最上面）条件的优先级最高，并且应用从后端提取值时，系统会提供与该条件关联的条件值。您可以在条件标签页中拖放条件来更改条件的优先级。

2. 如果没有条件求值为 true 的条件值，应用从后端提取值时，系统会提供 Remote Config 默认值。如果后端中不存在某个参数，或者默认值设为使用应用内默认值，当应用提取值时，系统不会为该参数提供任何值。

   注意：如果进行中的 Firebase A/B Testing 实验正在使用某个 Remote Config 参数，则实验值的优先级高于任何 Remote Config 条件值。

在您的应用中，参数值由 get 方法根据以下优先级列表返回

1. 如果从后端提取并激活了某个值，应用将使用该值。参数值一旦激活则永久有效。

2. 如果未从后端提取任何值，或者从 Remote Config 后端提取的值尚未激活，应用将使用应用内默认值。

   如需详细了解如何获取和设置默认值，请参阅下载 Remote Config 模板默认值。

3. 如果未设置应用内默认值，则应用会使用静态类型值（例如，对于 int 使用 0，对于 boolean 使用 false）。

下图总结了参数值在 Remote Config 后端中和您应用中的优先级排序：

参数值数据类型

借助 Remote Config，您可以为每个参数选择数据类型，并在模板更新之前根据该类型验证所有 Remote Config 的值。数据类型存储在 getRemoteConfig 请求中并会通过该请求返回。

支持的数据类型包括：

• String
• Boolean
• Number
• JSON

在 Firebase 控制台界面中，您可以从参数键旁边的下拉菜单中选择数据类型。在 REST API 中，可以使用参数对象中的 value_type 字段来设置类型。

注意：选择数据类型不会影响系统向客户端 SDK 返回值的方式。不过，请在您的应用中检查 get 方法是否将值转换回预期的数据类型。

参数组

借助 Remote Config，您可以将参数组合在一起，以获得更有条理的界面并提高可用性。

例如，假设您需要在发布新的登录功能时启用或停用三种不同的身份验证类型。借助 Remote Config，您可以创建三个参数以根据需要启用类型，然后将其整理到名为“新登录”的组中，无需添加前缀或特殊排序。

注意：参数组在 Firebase 控制台和 Remote Config REST API 中提供组织功能。但是，它们不会更改 SDK 引用参数的方式。

您可以使用 Firebase 控制台或 Remote Config REST API 创建参数组。您创建的每个参数组在 Remote Config 模板中都有一个唯一的名称。创建参数组时，请注意以下事项：

• 在任何时候，参数都只能包含在一个组中，并且参数键在所有参数中必须保持唯一。
• 参数组名称不得超过 256 个字符。
• 如果您同时使用 REST API 和 Firebase 控制台，请确保所有 REST API 逻辑都已更新，以便在发布时处理参数组。

使用 Firebase 控制台创建或修改参数组

您可以在 Firebase 控制台的参数标签页中对参数进行分组。如需创建或修改参数组，请按以下步骤操作：

1. 选择管理群组。
2. 选中您要添加的参数对应的复选框，然后选择移至群组。
3. 选择现有参数组，或通过输入名称和说明然后选择创建新群组来创建一个新组。 保存组后，可以使用发布更改按钮进行发布。

以编程方式创建参数组

Remote Config REST API 提供了一种自动创建和发布参数组的方法。 假设您熟悉 REST 并已完成对 API 请求授权的设置，则可以执行以下步骤以编程方式管理参数组：

1. 检索当前模板
2. 添加 JSON 对象以表示参数组
3. 使用 HTTP PUT 请求发布参数组。

parameterGroups 对象包含组键，其中包含嵌套说明和已分组参数的列表。请注意，每个组键都必须具有全局唯一性。

例如，以下是从模板修订版本中摘录的一个片段，其中添加了参数组“New Menu”和一个参数 pumpkin_spice_season：

{
  "parameters": {},
  "version": {
    "versionNumber": "1",

    …

  },
  "parameterGroups": {
    "new menu": {
      "description": "New Menu",
      "parameters": {
        "pumpkin_spice_season": {
          "defaultValue": {
            "value": "true"
          },
          "description": "Whether it's pumpkin spice season."
        }
      }
    }
  }
}

自定义信号条件

自定义信号条件值可用于将您在应用中定义和发送的任意信号与您根据 Remote Config 中的信号创建的条件进行匹配。这样，您就可以量身定制应用或客户端体验。

自定义信号条件适用于以下客户端环境：

• iOS：v11.8.0 或更高版本
• Android：v22.1.0 或更高版本（Firebase BoM v33.8.0 或更高版本）
• Web：v11.2.0 或更高版本

例如，假设您正在开发一个票务应用，希望在主屏幕上显示横幅。您可以使用客户端自定义信号条件，根据用户的位置和兴趣对这些横幅进行个性化设置。您可以执行以下操作：

1. 将 banner_image_url 和 banner_link 添加到 Remote Config 客户端模板中。这些属性表示横幅的图片以及与此图片关联的活动页面。
2. 使用值 city 和 preferred_event_category 设置应用中的自定义信号。
3. 为特定于客户端的 Remote Config 模板添加默认值，并根据您在上一步中设置的自定义信号创建条件值。
4. 为特定于客户端的 Remote Config 模板添加默认值，并为您定义的每个条件添加条件值。
5. 更新您的应用代码，以设置和使用自定义信号条件。

现在，您的应用可以在从 Remote Config 服务器提取这些参数时下载相应的 banner_image_url 和 banner_link。

限制

创建自定义信号条件时，您必须遵守以下限制：

• 自定义信号的数量：您最多可以创建 100 个自定义信号条件。
• 自定义信号名称：每个自定义信号名称最多可包含 250 个字符。
• 自定义信号值：每个自定义信号值最多可包含 500 个字符。使用正则表达式时，限制为 250 个字符。

注意：设置多个自定义信号条件时，请确保每个信号都符合这些限制。超出任何限制都会导致无法设置所有信号。

条件规则类型

Firebase 控制台支持以下规则类型。Remote Config REST API 中提供了等效功能，详见条件表达式参考文档。

规则类型	运算符	值	备注
应用	==	从与 Firebase 项目关联的应用 ID 列表中选择。	将某个应用添加到 Firebase 时，您需要输入一个软件包 ID 或 Android 软件包名称（用于指定一个在 Remote Config 规则中显示为应用 ID 的属性）。 请按如下方式使用此属性： 对于 Apple 平台：使用应用的 CFBundleIdentifier。您可以在常规标签页中找到软件包标识符，以在 Xcode 中用于应用主目标。 对于 Android 应用：使用应用的 applicationId。您可以在应用级 build.gradle 文件中找到 applicationId。
应用版本	对于字符串值： 完全匹配、 包含、 不包含、 包含正则表达式 对于数值： <、<=、=、!=、>、>=	指定您要定位的应用的版本。 使用此规则之前，您必须使用 App ID 规则选择与 Firebase 项目关联的 Android/Apple 应用。	对于 Apple 平台：使用应用的 CFBundleShortVersionString。 注意：确保您的 Apple 应用使用的是 Firebase Apple 平台 SDK 6.24.0 版或更高版本，因为在较早的版本中，系统不发送 CFBundleShortVersionString（请参阅版本说明）。 对于 Android：使用应用的 versionName。 此规则在进行字符串比较时区分大小写。当使用完全匹配、包含、不包含或包含正则表达式运算符时，您可以选择多个值。 使用包含正则表达式运算符时，您可以创建 RE2 格式的正则表达式。您的正则表达式可以与目标版本字符串的全部或部分文本匹配。您还可以使用 ^ 和 $ 定位点与目标字符串的开头部分、结尾部分或全部文本匹配。
版本号	对于字符串值： 完全匹配、 包含、 不包含、 正则表达式 对于数值： =、≠、>、≥、<、≤	指定您要定位的应用的 build。 使用此规则之前，您必须使用 App ID 规则选择与 Firebase 项目关联的 Apple 或 Android 应用。	此运算符仅适用于 Apple 和 Android 应用。它对应于 Apple 版应用的 CFBundleVersion 和 Android 版应用的 versionCode。此规则在进行字符串比较时区分大小写。 当使用完全匹配、包含、不包含或包含正则表达式运算符时，您可以选择多个值。 使用包含正则表达式运算符时，您可以创建 RE2 格式的正则表达式。您的正则表达式可以与目标版本字符串的全部或部分文本匹配。您还可以使用 ^ 和 $ 定位点与目标字符串的开头部分、结尾部分或全部文本匹配。
平台	==	iOS Android Web
操作系统	==	指定要定位到的操作系统。 使用此规则之前，您必须使用 App ID 规则选择与 Firebase 项目关联的 Web 应用。	当操作系统及其版本与指定列表中的目标值匹配时，此规则针对给定 Web 应用实例的求值为 true。
浏览器	==	指定要定位到的浏览器。 使用此规则之前，您必须使用 App ID 规则选择与 Firebase 项目关联的 Web 应用。	当浏览器及其版本与指定列表中的目标值匹配时，此规则针对给定 Web 应用实例的求值为 true。
设备类别	“是”“不是”	手机	此规则可评估访问您的 Web 应用的设备是移动设备还是非移动设备（桌面设备或控制台）。此规则类型仅适用于 Web 应用。
语言	包含于	选择一种或多种语言。	对于某个给定的应用实例而言，如果安装了该应用实例的设备使用的语言是所列语言之一，则此规则的求值结果为 true。
国家/地区	包含于	选择一个或多个国家或地区。	如果某个给定的应用实例位于所列出的任何一个国家或地区中，则对于该实例而言，此规则的求值结果为 true。可以使用请求中的设备的 IP 地址或由 Firebase Analytics 确定的国家/地区代码（如果 Analytics 与 Firebase 共享其数据）来确定设备国家/地区代码。
用户受众群体	至少包含一个	从您为自己的项目设置的 Google Analytics 受众群体名单中选择一个或多个受众群体。	此规则需要配合一条应用 ID 规则使用，以选择与您的 Firebase 项目关联的某个应用。 注意：由于许多 Analytics 受众群体是通过事件或用户属性定义的，而这些事件或属性可根据应用用户的行为或操作获得，因此对于某个给定的应用实例而言，用户（受众群体）规则可能需要一段时间才能生效。
用户属性	对于字符串值： 包含、 不包含、 完全匹配、 包含正则表达式 对于数值： =、≠、>、≥、<、≤ 注意：在客户端上，只能为用户属性设置字符串值。对于使用数值运算符的条件，Remote Config 会将相应用户属性的值转换为整数/浮点数。	从可用的 Google Analytics 用户属性列表中选择。	如需了解如何利用用户属性来针对非常具体的细分用户群量身打造应用，请参阅 Remote Config 和用户属性。 如需了解关于用户属性的更多信息，请参阅下列指南： 在 Apple 上设置用户属性 在 Android 上设置用户属性 当使用完全匹配、包含、不包含或包含正则表达式运算符时，您可以选择多个值。 使用包含正则表达式运算符时，您可以创建 RE2 格式的正则表达式。您的正则表达式可以与目标版本字符串的全部或部分文本匹配。您还可以使用 ^ 和 $ 定位点与目标字符串的开头部分、结尾部分或全部文本匹配。 注意：在创建 Remote Config 条件时无法使用自动收集的用户属性。
用户（随机百分比）	滑块（在 Firebase 控制台中。REST API 使用 <=、> 和 between 运算符）。	0-100	使用此字段可将更改应用于一批随机选取的应用实例（抽样比例大小最小可以是 .0001%），使用滑块微件将随机打乱的用户（应用实例）分组。 根据相关项目中定义的某个种子，每个应用实例都会永久映射到一个随机整数或小数。 种子值可以包含 1 到 32 个字符，这些字符可以是字母数字值、英文句点、连字符和/或下划线。 除非您修改种子值，否则规则将使用默认键（在 Firebase 控制台中显示为修改种子）。只需清除种子字段，就可以将规则恢复为使用默认键。 为了在给定的百分比范围内始终处理相同的应用实例，请针对各种条件使用相同的种子值。或者，通过指定新种子，为给定的百分比范围选择一组新的随机分配的应用实例。 例如，若要创建两个相关的条件，每个条件对应于应用用户中 5% 的人，且没有重合的用户，则您可以将一个条件配置为匹配 0% 到 5% 之间的百分比，将另一个条件配置为匹配 5% 到 10% 之间的范围。如需允许一些用户随机出现在这两个组中，请为每个条件中的规则使用不同的种子值。
导入的细分	包含于	选择一个或多个导入的细分。	此规则要求设置自定义导入的细分。
日期/时间	“之前”，“之后”	指定的日期和时间，可以是设备时区，也可以是指定时区，如“(GMT+11) 悉尼时间”。	将当前时间与设备提取时间进行比较。
首次打开	“之前”，“之后”	指定时区中的指定日期和时间。	匹配在指定的时间范围内首次打开目标应用的用户。 需要以下 SDK： Firebase SDK for Google Analytics Apple 平台 SDK v9.0.0+ 或 Android SDK v21.1.1+ (Firebase BoM v30.3.0+)
安装 ID	包含于	指定一个或多个要定位的安装 ID（最多 50 个）。	如果给定安装的 ID 位于以逗号分隔的值列表中，则此规则求值为 true。 如需了解如何获取安装 ID，请参阅检索客户端标识符。
用户存在	（不使用运算符）	定位当前项目中所有应用的全部用户。	使用此条件规则可匹配项目中的所有用户，无论他们使用的是哪种应用或平台。 使用 Remote Config 个性化时，您可以通过此运算符来确保项目中的所有用户都收到个性化值。
自定义信号	对于字符串值： 包含、 不包含、 完全匹配、 包含正则表达式 对于数值： =、≠、>、≥、<、≤ 对于版本值： =、≠、>、≥、<、≤	此规则在进行字符串比较时区分大小写。当使用“完全匹配”“包含”“不包含”或“包含正则表达式”运算符时，您可以选择多个值。使用“包含正则表达式”运算符时，您可以创建 RE2 格式的正则表达式。您的正则表达式可以与目标版本字符串的全部或部分文本匹配。您还可以使用 ^ 和 $ 定位点来与目标字符串的开头部分、结尾部分或全部文本匹配。 客户端环境支持以下数据类型： iOS：int、double Android：int、long、double Web：数字 数字，表示要匹配的版本号（例如 2.1.0）。	如需详细了解要使用的自定义信号条件和条件表达式，请参阅自定义信号条件和用于创建条件的元素。

搜索参数和条件

在 Firebase 控制台中，您可以使用 Remote Config 参数标签页顶部的搜索框来搜索项目的参数键、参数值和条件。

参数和条件的限制

在一个 Firebase 项目中，最多可以有 2000 个参数和 500 个条件。参数键最多可包含 256 个字符，且必须以下划线或英文字母（A-Z、a-z）开头，还可以包含数字。一个项目中所有参数值字符串的总长度不能超过 100 万个字符。

查看对参数和条件的更改

您可以在 Firebase 控制台中查看有关 Remote Config 模板的最新更改。对于每个参数和条件，您可以执行以下操作：

• 查看上次修改参数或条件的用户的姓名。

• 如果更改是在当天发生的，您可以查看自更改发布到有效 Remote Config 模板后经过的分钟数或小时数。

• 如果更改是在过去一天或数天内发生的，您可以查看更改发布到有效 Remote Config 模板的日期。

参数的更改历史记录

在 Remote Config 的参数页面上，上次发布者列会显示上次修改每个参数的用户以及上次发布更改的日期：

• 如需查看已分组参数的更改元数据，请展开参数组。

• 如需按发布日期进行升序或降序排序，请点击上次发布时间列标签。

条件的更改历史记录

在 Remote Config 的条件页面上，您可以在每个条件下方查看上次修改该条件的用户，并在上次修改时间旁边查看修改时间。

后续步骤

如需将您的 Firebase 项目和应用配置为使用 Remote Config，请参阅 Firebase Remote Config 使用入门。