您可以使用 Firebase 遠端設定在應用程式中定義參數,並在雲端更新參數的值,這樣就能在不發布應用程式更新的情況下修改應用程式的外觀與行為。本指南將引導您逐步瞭解如何開始使用,並提供部分程式碼範例,這些程式碼範例均可從 firebase/quickstart-js GitHub 存放區複製或下載。
步驟 1:新增並初始化遠端設定 SDK
如果您尚未 安裝 Firebase JS SDK 並初始化 Firebase,請先完成這項操作。
新增遠端設定 JS SDK 並初始化遠端設定:
網路模組 API
import { initializeApp } from "firebase/app"; import { getRemoteConfig } from "firebase/remote-config"; // TODO: Replace the following with your app's Firebase project configuration // See: https://firebase.google.com/docs/web/learn-more#config-object const firebaseConfig = { // ... }; // Initialize Firebase const app = initializeApp(firebaseConfig); // Initialize Remote Config and get a reference to the service const remoteConfig = getRemoteConfig(app);
網路命名空間 API
import firebase from "firebase/compat/app"; import "firebase/compat/remote-config"; // TODO: Replace the following with your app's Firebase project configuration // See: https://firebase.google.com/docs/web/learn-more#config-object const firebaseConfig = { // ... }; // Initialize Firebase firebase.initializeApp(firebaseConfig); // Initialize Remote Config and get a reference to the service const remoteConfig = firebase.remoteConfig();
這個物件可用來儲存應用程式內預設參數值、從遠端設定後端擷取更新後的參數值,以及控管將擷取的值提供給應用程式的時機。
步驟 2:設定最短擷取間隔
在開發期間,建議您設定相對較低的擷取時間間隔。詳情請參閱「節流」。
網路模組 API
remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
網路命名空間 API
remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
步驟 3:設定應用程式內預設參數值
您可以在遠端設定物件中設定應用程式內預設參數值,讓應用程式在連線至遠端設定後端前正常運作,如此如果後端未設定任何預設值,即可使用預設值。
網路模組 API
remoteConfig.defaultConfig = { "welcome_message": "Welcome" };
網路命名空間 API
remoteConfig.defaultConfig = { "welcome_message": "Welcome" };
如果您已設定遠端設定後端參數值,可以下載產生的 JSON 檔案,其中包含所有預設值,並加入應用程式套件:
REST
curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=JSON -o remote_config_defaults.json
Firebase 控制台
以下範例說明在應用程式中匯入及設定預設值的兩種不同方式。第一個範例使用 fetch
,對應用程式套件中的預設檔案發出 HTTP 要求:
const rcDefaultsFile = await fetch('remote_config_defaults.json'); const rcDefaultsJson = await rcDefaultsFile.json(); remoteConfig.defaultConfig = rcDefaultsJson;
下一個範例使用 require
,在建構期間將相關值編譯到應用程式中:
let rcDefaults = require('./remote_config_defaults.json'); remoteConfig.defaultConfig = rcDefaults;
步驟 4:取得要用於應用程式的參數值
您現在可以透過遠端設定物件取得參數值。如果之後在後端設定值、擷取並啟用這些值,應用程式即可使用這些值。如要取得這些值,請呼叫 getValue()
方法,並提供參數鍵做為引數。
網路模組 API
import { getValue } from "firebase/remote-config"; const val = getValue(remoteConfig, "welcome_messsage");
網路命名空間 API
const val = remoteConfig.getValue("welcome_messsage");
步驟 5:設定參數值
使用 Firebase 主控台或遠端設定後端 API 即可建立新的伺服器端預設值,根據您想要的條件邏輯或使用者指定目標來覆寫應用程式內的值。本節將逐步引導您完成 Firebase 控制台建立這些值的步驟。
- 在 Firebase 控制台開啟專案。
- 從選單中選取「Remote Config」,查看遠端設定資訊主頁。
- 定義與您在應用程式中定義的參數名稱相同的參數。您可以為每個參數設定預設值 (最終覆寫應用程式內預設值),此外也可以設定條件值。詳情請參閱遠端設定參數與條件。
步驟 6:擷取並啟用值
- 如要從遠端設定後端擷取參數值,請呼叫
fetchConfig()
方法。系統會擷取您在後端設定的任何值,並儲存在遠端設定物件中。 - 如要讓應用程式取得擷取的參數值,請呼叫
activate()
方法。
如果您想在單一呼叫中擷取及啟用值,請使用 fetchAndActivate()
,如以下範例所示:
網路模組 API
import { fetchAndActivate } from "firebase/remote-config"; fetchAndActivate(remoteConfig) .then(() => { // ... }) .catch((err) => { // ... });
網路命名空間 API
remoteConfig.fetchAndActivate() .then(() => { // ... }) .catch((err) => { // ... });
這些更新後的參數值會影響應用程式的行為與外觀,因此建議您一次啟用擷取的值,以確保使用者享有流暢的使用體驗,例如使用者下次開啟您的應用程式時。詳情請參閱遠端設定載入策略。
調節
如果應用程式在短時間內擷取太多次,擷取呼叫可能會受到限制。在這種情況下,SDK 會擲回 FETCH_THROTTLE
錯誤。建議您擷取這個錯誤,並以指數輪詢模式重試,以便在後續的擷取要求之間等待較長的間隔。
在應用程式開發期間,您可能想要經常 (每小時多次) 重新整理快取,以便在開發及測試應用程式時快速疊代。如要配合有眾多開發人員的專案快速疊代,您可以在應用程式中暫時新增擷取時間間隔下限 (Settings.minimumFetchIntervalMillis
) 的屬性。
遠端設定的預設實際工作環境擷取時間間隔為 12 小時。也就是說,無論實際發出多少擷取呼叫,設定在 12 小時內都不會從後端多次擷取設定。具體而言,最小擷取間隔順序如下:
Settings.minimumFetchIntervalMillis
中的參數。- 預設值是 12 小時。
後續步驟
如果您尚未瞭解遠端設定的用途,請先查看一些重要概念和進階策略說明文件,包括: