在 Android 程式碼研究室中整合遠端設定

1. 簡介

上次更新時間：2021 年 3 月 9 日

什麼是 Firebase 遠端設定？

Firebase 遠端設定是一項雲端服務，可讓您變更應用程式的行為和外觀，而且不必要求使用者下載應用程式更新，完全免費。您可利用這個功能建立應用程式內預設值來控制應用程式行為和外觀，之後還能透過 Firebase 控制台或遠端設定後端 API，為自家應用程式的所有或部分使用者覆寫應用程式內預設值，應用程式會控管更新套用的時間，並可頻繁檢查更新，且套用更新時對效能的影響微乎其微。

運作方式

遠端設定包含用戶端程式庫，可處理擷取及快取參數值等重要工作，同時讓您控管啟用新值時機，確保新值不會影響應用程式的使用者體驗。您可以控管變更時間，確保應用程式體驗不受影響。

遠端設定用戶端程式庫 get 方法提供參數值的單一存取點。應用程式會使用與取得應用程式預設值相同的邏輯來取得伺服器端值，因此您不必編寫大量程式碼，就能在應用程式中新增遠端設定功能。

如要覆寫應用程式內預設值，請使用 Firebase 控制台或遠端設定後端 API，建立與應用程式所用參數同名的參數。您可以為每個參數設定伺服器端預設值來覆寫應用程式內預設值，也可以建立條件值，針對符合特定條件的應用程式例項覆寫應用程式內預設值。這張圖表顯示遠端設定後端和應用程式中的參數值優先順序：

課程內容

如何導入 Firebase 遠端設定
如何使用 Firebase 遠端設定變更值，不必更新應用程式

軟硬體需求

最新版 Android Studio
Firebase 帳戶
(建議，但非必要) 用來執行應用程式的實體 Android 裝置
具備 Java 或 Kotlin 的基本知識

2. 開始設定

(選用) 下載程式碼範例

在本程式碼研究室中，您將建構自己的測試應用程式，但如果想查看及執行現有的範例應用程式，可以下載快速入門程式碼範例。

點選下方按鈕即可下載這個程式碼研究室的所有程式碼：

將下載的 ZIP 檔案解壓縮。這會解壓縮名為「quickstart-android-master」的根資料夾。

...或從指令列複製 GitHub 存放區。

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

存放區包含多個資料夾。我們將使用 config 資料夾。

(選用) 匯入程式碼範例

啟動 Android Studio，然後在歡迎畫面中選擇「Import project」。然後開啟下載的資料夾，選取「config」資料夾。然後按一下「開啟」。

建立新的 Android 專案

在 Android Studio 中建立新專案
選取「基礎活動」
在「設定專案」畫面中：
為專案命名，系統會自動產生套件名稱和儲存位置。
語言：Java
最低 SDK 16

3. 將 Firebase 和 Firebase Analytics 新增至 Android 專案

建立 Firebase 專案

將 Firebase 加入 Android 應用程式前，請先建立要連結至該 iOS 應用程式的 Firebase 專案。如要進一步瞭解 Firebase 專案，請參閱「瞭解 Firebase 專案」一文。

在 Firebase 控制台中，按一下「新增專案」，然後選取或輸入「專案名稱」。

如果您有現成的 Google Cloud Platform (GCP) 專案，可以從下拉式選單中選取專案，將 Firebase 資源新增至該專案。

(選用) 如果要建立新專案，可以編輯「專案 ID」。

Firebase 會自動為 Firebase 專案指派專屬 ID。請參閱「瞭解 Firebase 專案」，進一步瞭解 Firebase 如何使用專案 ID。

按一下「繼續」。
為專案設定 Google Analytics，以便透過下列任一 Firebase 產品獲得最佳體驗：

Firebase Crashlytics
Firebase 預測
Firebase 雲端通訊
Firebase 應用程式內通訊
Firebase 遠端設定
Firebase A/B 測試

系統提示時，請選取使用現有的 Google Analytics 帳戶，或建立新帳戶。如果選擇建立新帳戶，請選取 Analytics 報表位置，然後接受專案的資料共用設定和 Google Analytics 條款。

按一下「建立專案」 (如果您使用現有的 GCP 專案，請按一下「新增 Firebase」)。

Firebase 會自動為 Firebase 專案佈建資源。程序完成後，系統會將您帶往 Firebase 主控台的 Firebase 專案總覽頁面。

向 Firebase 註冊應用程式

建立 Firebase 專案後，你可以加入 Android 應用程式。

如要進一步瞭解將應用程式新增至 Firebase 專案的最佳做法和注意事項，包括如何處理多個建構變化版本，請參閱「瞭解 Firebase 專案」。

前往 Firebase 主控台。
在「專案總覽」頁面頂端，按一下「Android」Android圖示來啟動設定工作流程。如果已將應用程式新增至 Firebase 專案，請按一下「新增應用程式」顯示平台選項。
在「Android 套件名稱」欄位中，輸入應用程式的套件名稱。
(選用) 輸入「應用程式暱稱」。
由於這項專案不需要 SHA-1，請將 SHA-1 欄位留空。
按一下 [Register app] (註冊應用程式)。

新增 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'

// Add the following line:

apply plugin: ‘com.google.gms.google-services' // Google Services plugin

android {

// ...

}

在 Android 應用程式中新增 Firebase SDK

對於遠端設定，您需使用 Google Analytics，才能條件式指定應用程式執行個體的使用者屬性和目標對象。請確認專案已啟用 Google Analytics。

(範例快速入門程式碼已完成這項操作)

使用 Firebase Android BoM，在模組 (應用程式層級) Gradle 檔案 (通常為 app/build.gradle) 中，宣告遠端設定 Android 程式庫的依附元件。使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。

此外，您也必須在設定 Analytics 時，將 Google Analytics 專用 Firebase SDK 加進應用程式。在依附元件下方新增下列程式碼：

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. 查看遠端設定的主要元件

現在我們要回顧在應用程式中使用遠端設定的步驟。這些步驟已在快速入門程式碼研究室的程式碼中完成。請在檢查快速入門導覽課程程式碼研究室的程式碼時，使用這個部分瞭解具體情況。

1. 取得遠端設定單例模式物件

取得遠端設定物件執行個體，並設定最短擷取間距，才能經常更新：

MainActivity.java

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

單例物件可用來儲存應用程式內預設參數值、從後端擷取更新的參數值，以及控管擷取的值何時可供應用程式使用。

開發期間建議設定相對較短的最低擷取間隔。詳情請參閱「節流」。

2. 設定應用程式內預設參數值

您可以在遠端設定物件中設定應用程式內預設參數值，讓應用程式在連線至遠端設定後端前正常運作，並在後端未設定任何值時提供預設值。

您可以使用 Map 物件或儲存在應用程式 res/xml 資料夾中的 XML 資源檔案，定義一組參數名稱和預設參數值。遠端設定快速入門範例應用程式會使用 XML 檔案定義預設參數名稱和值。以下說明如何自行建立 XML 檔案：

在 res 資料夾下建立 xml 資料夾。

在新建立的 xml 資料夾上按一下滑鼠右鍵，然後建立檔案。

設定預設值。在下一節中，您將嘗試變更遠端設定快速入門 XML 檔案中的預設值。
使用 setDefaultsAsync(int) 將這些值新增至遠端設定物件，如下所示：

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. 取得要在應用程式中使用的參數值

現在您可以從遠端設定物件取得參數值。如果您在後端設定值，然後擷取並啟用這些值，應用程式就能使用這些值。否則，您會取得使用 setDefaultsAsync(int) 設定的應用程式內參數值。如要取得這些值，請呼叫下列方法，將參數鍵做為引數提供，並對應至應用程式預期的資料類型：

4. 擷取並啟用值

如要從遠端設定後端擷取參數值，請呼叫 fetch() 方法。系統會擷取您在後端中設定的所有值，並儲存在遠端設定物件中。
如要讓應用程式使用擷取的參數值，請呼叫 activate() 方法。如要透過一次呼叫擷取並啟用值，可以使用 fetchAndActivate() 要求從遠端設定後端擷取值，並提供給應用程式：

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();
            }
        });

由於這些更新後的參數值會影響應用程式的行為和外觀，因此您應在確保使用者體驗順暢的時間點啟用擷取的值，例如使用者下次開啟應用程式時。如需更多資訊和範例，請參閱「遠端設定載入策略」。

節流

如果應用程式在短時間範圍內擷取過多資料，擷取呼叫就會受到節流，且 SDK 會傳回 FirebaseRemoteConfigFetchThrottledException。在 SDK 17.0.0 版之前，上限為 60 分鐘內 5 次擷取要求 (新版限制較寬鬆)。

在應用程式開發期間，您可能需要頻繁擷取及啟用設定 (每小時多次)，以便在開發及測試應用程式時快速疊代。如要在專案中快速疊代，並支援最多 10 位開發人員，您可以在應用程式中暫時設定 FirebaseRemoteConfigSettings 物件，並將最低擷取間隔時間設為較短的時間 (setMinimumFetchIntervalInSeconds)。

遠端設定的預設最短擷取間隔為 12 小時，也就是說，無論實際發出多少擷取呼叫，系統在 12 小時內最多只會從後端擷取一次設定。具體來說，系統會依下列順序決定最短擷取間隔：

fetch(long) 中的參數
FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long) 中的參數
預設值為 12 小時

如要將最短擷取時間間隔設為自訂值，請使用 FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)。

5. 使用遠端設定變更應用程式行為

變更應用程式內預設參數

開啟 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 版本的「開啟」。

查看主畫面上的歡迎訊息。

在遠端設定後端中設定參數值

現在來測試透過遠端設定傳送值。您可以使用 Firebase 控制台或遠端設定後端 API 建立新的伺服器端預設值，並根據所需的條件式邏輯或使用者指定目標，覆寫應用程式內的值。本節說明如何在 Firebase 控制台中建立這些值。

開啟 Firebase 控制台，然後開啟專案。
在「參與」部分的左側選單中選取「遠端設定」，即可查看遠端設定資訊主頁。
在 新增參數下方，輸入 Parameter key.。在 Default value下方，新增所需文字。然後按一下「新增參數」。在本程式碼研究室中，我們將使用 res/xml/remote_config_defaults.xml 檔案中的參數鍵。詳情請參閱下表：

參數鍵	預設值 (`remote_config_defaults.xml`)	說明
loading_phrase	正在擷取設定...	字串；擷取遠端設定值時顯示。
welcome_message_caps	false	布林值；如果為 true，則將 welcome_message 變更為全大寫
welcome_message	歡迎使用我的超棒應用程式！	字串；歡迎訊息

螢幕截圖範例：

參數新增完畢後，請按一下「發布變更」。
再次在模擬器或裝置上執行應用程式，這次請點選「Fetch Remote Welcome」按鈕。

歡迎訊息應根據遠端設定參數和值更新！

6. 恭喜

恭喜！您已成功使用遠端設定變更歡迎訊息！您還能透過許多其他方式，運用遠端設定變更及自訂應用程式。請參閱下列其他資源：

在 Android 程式碼研究室中整合遠端設定

1. 簡介

什麼是 Firebase 遠端設定？

運作方式

課程內容

軟硬體需求

2. 開始設定

(選用) 下載程式碼範例

(選用) 匯入程式碼範例

建立新的 Android 專案

3. 將 Firebase 和 Firebase Analytics 新增至 Android 專案

建立 Firebase 專案

向 Firebase 註冊應用程式

新增 Firebase 設定檔

專案層級的 build.gradle (<project>/build.gradle)：

應用程式層級的 build.gradle (<project>/<app-module>/build.gradle)：

在 Android 應用程式中新增 Firebase SDK

app/build.gradle

將專案與 Gradle 檔案同步

4. 查看遠端設定的主要元件

1. 取得遠端設定單例模式物件

MainActivity.java

2. 設定應用程式內預設參數值

MainActivity.java

3. 取得要在應用程式中使用的參數值

4. 擷取並啟用值

MainActivity.java

節流

5. 使用遠端設定變更應用程式行為

變更應用程式內預設參數

確認應用程式內預設值變更

在遠端設定後端中設定參數值

6. 恭喜

專案層級的 build.gradle (`<project>/build.gradle`)：

應用程式層級的 build.gradle (`<project>/<app-module>/build.gradle`)：