将 App Check 与调试提供程序搭配使用 (Android)

为应用启用 App Check 后,如果您希望在 App Check 通常不会归类为有效提供程序的环境(例如开发期间的模拟器)或持续集成 (CI) 环境中运行您的应用,可以创建应用的调试 build,该 build 使用 App Check 调试提供程序,而不是真正的证明提供程序。

在模拟器中使用调试提供程序

如需在模拟器中以交互方式运行应用时(例如在开发期间)使用调试提供程序,请执行以下操作:

  1. 在您的模块(应用级)Gradle 文件(通常是 <project>/<app-module>/build.gradle.kts<project>/<app-module>/build.gradle)中,添加 App Check Android 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.4"))
    
        // 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 库的兼容版本。

    (替代方法) 在不使用 BoM 的情况下添加 Firebase 库依赖项

    如果您选择不使用 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:17.1.2")
    }
    
    是否想要查找 Kotlin 专用的库模块?2023 年 10 月 (Firebase BoM 32.5.0) 开始,Kotlin 和 Java 开发者可以依赖于主库模块(如需了解详情,请参阅关于此计划的常见问题解答)。

  2. 在调试 build 中,将 App Check 配置为使用调试提供程序工厂:

    Kotlin+KTX

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

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
    FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
    firebaseAppCheck.installAppCheckProviderFactory(
            DebugAppCheckProviderFactory.getInstance());
  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 部分中,从应用的溢出菜单中选择管理调试令牌。然后,注册您在上一步中记录的调试令牌。

    “管理调试令牌”菜单项的屏幕截图

注册令牌后,Firebase 后端服务会将其视为有效的令牌。

由于此令牌允许用户在没有有效设备的情况下访问您的 Firebase 资源,因此请务必确保此令牌的私密性。请勿将其提交到公共代码库;如果注册的令牌被盗用,请立即在 Firebase 控制台中撤消该令牌。

在 CI 环境中使用调试提供程序进行单元测试

如需在持续集成 (CI) 环境中使用调试提供程序进行单元测试,请执行以下操作:

  1. 在 Firebase 控制台的 App Check 部分中,从应用的溢出菜单中选择管理调试令牌。然后,创建一个新的调试令牌。在下一步中,您需要用到该令牌。

    由于此令牌允许用户在没有有效设备的情况下访问您的 Firebase 资源,因此请务必确保此令牌的私密性。请勿将其提交到公共代码库;如果注册的令牌被盗用,请立即在 Firebase 控制台中撤消该令牌。

    “管理调试令牌”菜单项的屏幕截图

  2. 将您刚刚创建的调试令牌添加到 CI 系统的安全密钥存储区(例如 GitHub Actions 的加密 Secret 或 Travis CI 的加密变量)中。

  3. 如有必要,请配置 CI 系统,以使调试令牌在 CI 环境中作为环境变量使用。以 APP_CHECK_DEBUG_TOKEN_FROM_CI 之类的形式为变量命名。

  4. 在您的模块(应用级)Gradle 文件(通常是 <project>/<app-module>/build.gradle.kts<project>/<app-module>/build.gradle)中,添加 App Check Android 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

    Kotlin+KTX

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.4"))
    
        // 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 库的兼容版本。

    (替代方法) 在不使用 BoM 的情况下添加 Firebase 库依赖项

    如果您选择不使用 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:17.1.2")
    }
    
    是否想要查找 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:32.7.4"))
    
        // 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 库的兼容版本。

    (替代方法) 在不使用 BoM 的情况下添加 Firebase 库依赖项

    如果您选择不使用 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:17.1.2")
    }
    
    是否想要查找 Kotlin 专用的库模块?2023 年 10 月 (Firebase BoM 32.5.0) 开始,Kotlin 和 Java 开发者可以依赖于主库模块(如需了解详情,请参阅关于此计划的常见问题解答)。

  5. 将以下代码添加到 CI build 变体的配置中:

    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 后端服务会将其发送的令牌视为有效的令牌。