搭配 Android 偵錯供應商使用 App Check

為應用程式註冊 App Check 後，如果您想在 App Check 通常不會歸類為有效的環境中 (例如開發期間的模擬器，或是從持續整合 (CI) 環境) 執行應用程式，您可以建立採用 App Check 偵錯供應商 (而非實際認證供應商) 的應用程式偵錯版本。

在模擬器中使用偵錯提供者

如要在以互動方式 (例如開發期間) 在模擬器中執行應用程式時使用偵錯提供者，請按照下列步驟操作：

  1. 在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，新增 Android 適用的 App Check 程式庫依附元件。建議您使用 Firebase Android BoM 控管程式庫的版本管理。

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

    // Add the dependencies for the App Check libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug")
}

    只要使用 Firebase Android BoM，您的應用程式就會一律使用相容的 Firebase Android 程式庫版本。

    (替代做法) 新增 Firebase 程式庫依附元件，「不」使用 BoM

    如果選擇不使用 Firebase BoM，就必須在依附元件行中指定每個 Firebase 程式庫版本。

    請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 來管理程式庫版本，以確保所有版本都相容。

    dependencies {
    // Add the dependencies for the App Check libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug:18.0.0")
}
    在尋找 Kotlin 專用的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0) 起，Kotlin 和 Java 開發人員都能使用主要的程式庫模組 (詳情請參閱這項計畫的常見問題)。

  2. 在偵錯版本中，將 App Check 設為使用偵錯提供者工廠：

    Kotlin+KTX 

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)
    MainActivity.kt

    Java 

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());
    MainActivity.java

  3. 啟動應用程式，並觸發對 Firebase 後端服務的呼叫。當 SDK 嘗試傳送要求至後端時，系統會記錄本機偵錯權杖。例如：

    D DebugAppCheckProvider: Enter this debug secret into the allow list in
the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

  4. 在 Firebase 控制台的「App Check」(App Check) 部分，從應用程式的溢位選單中選擇「Manage debug token」。接著，註冊您在先前步驟中記錄的偵錯權杖。

    「管理偵錯權杖」選單項目的螢幕截圖

註冊權杖後，Firebase 後端服務會接受該權杖的有效性。

由於這個權杖可在沒有有效裝置的情況下存取您的 Firebase 資源，因此請務必確保其私密性。請勿將其提交至公開存放區。如果註冊的憑證遭駭，請在 Firebase 控制台立即撤銷該權杖。

使用偵錯供應商在 CI 環境中進行單元測試

如要在持續整合 (CI) 環境中使用偵錯供應商進行單元測試，請按照下列步驟操作：

  1. 在 Firebase 控制台的「App Check」(App Check) 部分，從應用程式的溢位選單中選擇「Manage debug token」。接著建立新的偵錯權杖。下個步驟中會會用到這組權杖。

    由於這個權杖可讓您在不使用有效裝置的情況下存取 Firebase 資源，因此請務必確保憑證不外洩。請勿將其提交至公開存放區。如果註冊的憑證遭駭，請在 Firebase 控制台立即撤銷該權杖。

    「管理偵錯權杖」選單項目的螢幕截圖

  2. 將您剛剛建立的偵錯權杖新增至 CI 系統的安全金鑰儲存庫 (例如 GitHub Actions 的加密密鑰或 Travis CI 的加密變數)。

  3. 如有需要，請設定持續整合系統，以在 CI 環境中提供偵錯權杖做為環境變數。以類似 APP_CHECK_DEBUG_TOKEN_FROM_CI 的形式為變數命名。

  4. 在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，新增 Android 適用的 App Check 程式庫依附元件。建議您使用 Firebase Android BoM 控管程式庫的版本管理。

    Kotlin+KTX 

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

    // Add the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug")
}

    只要使用 Firebase Android BoM，您的應用程式就會一律使用相容的 Firebase Android 程式庫版本。

    (替代做法) 新增 Firebase 程式庫依附元件，「不」使用 BoM

    如果選擇不使用 Firebase BoM，就必須在依附元件行中指定每個 Firebase 程式庫版本。

    請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 來管理程式庫版本，以確保所有版本都相容。

    dependencies {
    // Add the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug:18.0.0")
}
    在尋找 Kotlin 專用的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0) 起，Kotlin 和 Java 開發人員都能使用主要的程式庫模組 (詳情請參閱這項計畫的常見問題)。

    Java 

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

    // Add the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug")
}

    只要使用 Firebase Android BoM，您的應用程式就會一律使用相容的 Firebase Android 程式庫版本。

    (替代做法) 新增 Firebase 程式庫依附元件，「不」使用 BoM

    如果選擇不使用 Firebase BoM，就必須在依附元件行中指定每個 Firebase 程式庫版本。

    請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 來管理程式庫版本，以確保所有版本都相容。

    dependencies {
    // Add the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-appcheck-debug:18.0.0")
}
    在尋找 Kotlin 專用的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0) 起，Kotlin 和 Java 開發人員都能使用主要的程式庫模組 (詳情請參閱這項計畫的常見問題)。

  5. 將以下內容新增至 CI 建構變數的設定：

    testInstrumentationRunnerArguments["firebaseAppCheckDebugSecret"] =
    System.getenv("APP_CHECK_DEBUG_TOKEN_FROM_CI") ?: ""

  6. 在測試類別中，使用 DebugAppCheckTestHelper 納入任何需要 App Check 權杖的程式碼：

    Kotlin+KTX 

    @RunWith(AndroidJunit4::class)
class MyTests {
    private val debugAppCheckTestHelper =
        DebugAppCheckTestHelper.fromInstrumentationArgs()

    @Test
    fun testWithDefaultApp() {
        debugAppCheckTestHelper.withDebugProvider {
            // Test code that requires a debug AppCheckToken.
        }
    }

    @Test
    fun testWithNonDefaultApp() {
        debugAppCheckTestHelper.withDebugProvider(
            FirebaseApp.getInstance("nonDefaultApp")
        ) {
            // Test code that requires a debug AppCheckToken.
        }
    }
}

    Java 

    @RunWith(AndroidJunit4.class)
public class YourTests {
    private final DebugAppCheckTestHelper debugAppCheckTestHelper =
            DebugAppCheckTestHelper.fromInstrumentationArgs();

    @Test
    public void testWithDefaultApp() {
        debugAppCheckTestHelper.withDebugProvider(() -> {
            // Test code that requires a debug AppCheckToken.
        });
    }

    @Test
    public void testWithNonDefaultApp() {
        debugAppCheckTestHelper.withDebugProvider(
                FirebaseApp.getInstance("nonDefaultApp"),
                () -> {
                    // Test code that requires a debug AppCheckToken.
                });
    }
}

當您在 CI 環境中執行應用程式時，Firebase 後端服務會接受其傳送的有效權杖。