用戶端範本中的遠端設定參數和條件

您可以將用戶端範本中的 Remote Config 參數和值，提供給任何實作 Remote Config Firebase 用戶端 SDK 的應用程式執行個體，包括 Apple、Android、Web、Flutter、Unity 和 C++ 應用程式。

使用 Firebase 控制台或Remote Config後端 API 時，您需要定義一或多個參數 (鍵/值組合)，並為這些參數提供應用程式內預設值。您可以定義參數值，覆寫應用程式內預設值。參數鍵和參數值都是字串，但在應用程式中使用這些值時，參數值可以轉換為其他資料類型。

您可以使用 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 規則，根據 OS 類型顯示不同的圖片：

或者，您也可以使用時間條件，控制應用程式顯示特殊促銷項目的時間。

一個參數可以有多個使用不同條件的條件值，且參數可以在專案內共用條件。在 Firebase 控制台中，依序前往「DevOps & Engagement」>「遠端設定」>「參數」頁面，查看各參數條件值的擷取百分比。這項指標代表過去 24 小時內，收到各個值的要求百分比。

使用 Firebase 控制台新增、編輯、重新排序或刪除條件

您可以在 Firebase 控制台中建立、編輯、重新排序及刪除指定條件。專案中的參數會共用條件。以下說明如何管理條件：

1. 在 Firebase 控制台中，依序前往「DevOps & Engagement」 >「遠端設定」 >「Conditions」頁面 (或在「Parameters」頁面中選取「Manage conditions」)。
2. 新增條件：按一下「Add condition」(新增條件) (或「Create your first condition」(建立第一個條件))，輸入定義指定目標的名稱，然後選取一或多個指定規則。
3. 編輯條件：按一下條件名稱或編輯圖示，視需要修改規則，然後按一下「儲存」。
4. 變更條件優先順序：在「Conditions」(條件) 頁面上，拖曳條件的抓取控點即可重新排序。清單中較高的條件優先於較低的條件。
5. 刪除條件：按一下要移除的條件旁的刪除圖示。如果條件由任何參數參照，移除條件也會一併移除相關聯的條件值。

儲存條件變更後，請使用「Publish changes」(發布變更) 發布範本。

IPv6 限制與 IP 存取控管

搭配使用 IP 型存取政策時，Remote Config 對 IPv6 的支援有限。如果貴組織限制存取特定公開 IP 範圍，透過 IPv6 網路連線可能會導致下列問題：

• 控制台存取權：您可能無法使用 Firebase 控制台中的特定 Remote Config 功能，例如載入資料或設定指定目標。
• 用戶端存取權：用戶端應用程式可能會發生 PERMISSION_DENIED 錯誤。

為避免發生這些問題，請將網路設為使用 IPv4，或將必要的 Firebase IP 範圍加入貴組織的許可清單。

參數值優先順序

一個參數可能有多個相關聯的條件值。下列規則會決定從 Remote Config 範本擷取的值，以及在特定時間點用於特定應用程式例項的值：

1. 首先，系統會針對特定用戶端要求中評估為 true 的任何條件，套用條件值。如果多個條件的評估結果為 true，系統會優先採用 Firebase 控制台使用者介面中顯示的最上方條件，並在應用程式從後端擷取值時，提供與該條件相關聯的條件值。在「Conditions」(條件) 頁面中拖曳條件，即可變更條件的優先順序。

2. 如果沒有任何條件式值的條件評估結果為 true，則應用程式從後端擷取值時，會提供 Remote Config 的預設值。如果後端沒有參數，或預設值設為「Use in-app default」(使用應用程式內預設值)，則應用程式擷取值時，不會提供該參數的值。

在應用程式中，get 方法會根據下列優先順序清單傳回參數值

1. 如果值是從後端擷取並啟用，應用程式會使用擷取的值。啟用的參數值會保留。

2. 如果未從後端擷取任何值，或從 Remote Config 後端擷取的值尚未啟用，應用程式會使用應用程式內預設值。

   如要進一步瞭解如何取得及設定預設值，請參閱「下載 Remote Config 範本預設值」。

3. 如果未設定應用程式內預設值，應用程式會使用靜態類型值 (例如 int 的 0 和 boolean 的 false)。

下圖摘要說明 Remote Config 後端和應用程式中參數值的優先順序：

參數值資料類型

Remote Config 可讓您為每個參數選取資料類型，並在範本更新前，根據該類型驗證所有 Remote Config 值。資料類型會儲存並在 getRemoteConfig 要求中傳回。

支援的資料類型如下：

• String
• Boolean
• Number
• JSON

在 Firebase 控制台 UI 中，您可以從參數索引鍵旁的下拉式選單中選取資料類型。在 REST API 中，可以使用參數物件中的 value_type 欄位設定類型。

參數群組

Remote Config 可將參數分組，讓使用者介面更井然有序，並提升可用性。

舉例來說，假設您在推出新的登入功能時，需要啟用或停用三種不同的驗證類型。使用 Remote Config，您可以建立三個參數來啟用所需類型，然後將這些參數整理到名為「New login」的群組中，不必新增前置字元或特殊排序。

您可以使用 Firebase 控制台或 Remote Config REST API 建立參數群組。您建立的每個參數群組在 Remote Config 範本中都有不重複的名稱。建立參數群組時，請注意下列事項：

• 參數一次只能加入一個群組，且參數鍵在所有參數中仍須不重複。
• 參數群組名稱長度上限為 256 個半形字元。
• 如果您同時使用 REST API 和 Firebase 控制台，請務必更新所有 REST API 邏輯，以便在發布時處理參數群組。

使用 Firebase 控制台建立或修改參數群組

您可以在 Firebase 控制台中將參數分組。建立或修改群組的方法如下：

1. 在 Firebase 控制台中，依序前往「DevOps & Engagement」 >「遠端設定」 >「Parameters」(參數) 頁面。
2. 選取「管理群組」。
3. 勾選要新增的參數，然後選取「Move to group」(移至群組)。
4. 選取現有群組，或輸入名稱和說明，然後選取「Create new group」(建立新群組)，建立新群組。儲存群組後，您可以使用「Publish changes」(發布變更) 按鈕發布群組。

透過程式建立群組

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：11.8.0 以上版本
• Android：22.1.0 以上版本 (Firebase BoM 33.8.0 以上版本)
• 網頁：v11.2.0 以上版本
• Flutter：Flutter BoM 3.6.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 控制台，依序點選「DevOps & Engagement」>「遠端設定」>「參數」，然後使用頁面頂端的搜尋框。

參數和條件限制

在 Firebase 專案中，最多可有 3,000 個參數和 2,000 個條件。參數鍵長度上限為 256 個半形字元，開頭必須是底線或英文字母 (A 至 Z、a 至 z)，其他部分則可使用數字。專案中參數值字串的總長度不得超過 1,000,000 個字元。此外，根據使用者屬性設定的條件規則，最多可包含 100 個使用者屬性值。如需完整的限制清單，請參閱「配額與限制」。

查看參數和條件的變更

您可以透過Firebase控制台查看 Remote Config 範本的最新變更。您可以對個別參數和條件執行下列操作：

• 查看上次修改參數或條件的使用者名稱。

• 如果變更發生在當天，請查看變更發布到有效 Remote Config 範本後經過的分鐘數或小時數。

• 如果變更發生在一天或多天前，請查看變更發布至有效Remote Config範本的日期。

參數變更記錄

在 Firebase 控制台中，依序前往「DevOps & Engagement」 >「遠端設定」 >「Parameters」(參數) 頁面。「上次發布」欄會顯示上次修改各參數的使用者，以及變更的上次發布日期：

• 如要查看分組參數的變更中繼資料，請展開參數群組。

• 如要依發布日期遞增或遞減排序，請按一下「Last published」(上次發布時間) 欄標籤。

條件變更記錄

在 Firebase 控制台中，依序前往「DevOps & Engagement」 >「遠端設定」 >「Conditions」(條件) 頁面。在每個條件下方的「上次修改時間」旁，您可以看到上次修改條件的使用者和修改日期。

後續步驟

如要設定 Firebase 專案和應用程式，以便使用 Remote Config，請參閱「開始使用 Firebase Remote Config」。