Get started using App Check with reCAPTCHA Enterprise in Flutter apps

Select platform: iOS+ Android Web Flutter


This page shows you how to set up App Check in a Flutter app, using the reCAPTCHA Enterprise provider. App Check helps to ensure that only your app can access your project's backend resources. To learn more, review our overview of App Check.

App Check requires the use of score-based reCAPTCHA keys, which makes it invisible to users. This means that the reCAPTCHA Enterprise provider won't require users to solve a challenge at any time.

If your use case requires reCAPTCHA Enterprise features not implemented by App Check, or if you want to use App Check with your own custom provider, see Implement a custom App Check provider.

1. Set up your Firebase project

  1. If you haven't already, install and initialize Firebase in your Flutter project.

  2. In the Google Cloud console, go to the Fraud Defense page, and do the following for the reCAPTCHA Enterprise provider:

    1. Make sure that you're in the correct project (see the project picker at the top of the screen).

    2. If prompted, enable the reCAPTCHA Enterprise API.

    3. Create a key based on your target platform:

      iOS+

      Create an iOS-type key, and specify your app's bundle ID (for example, com.example.my_app).

      • Make sure that you enter the same bundle ID that you provided when you created your Firebase Apple App in your Firebase project. The bundle ID value is case-sensitive.

      • For App Check, each bundle ID can only correspond to a single reCAPTCHA key.

      Android

      Create an Android-type key, and specify your app's package name (for example, com.example.my_app).

      • Make sure that you enter the same package name that you provided when you created your Firebase Android App in your Firebase project. The package name value is case-sensitive.

      • For App Check, each package name can only correspond to a single reCAPTCHA key.

      Web

      Create a Web-type key, and specify each of the domains for your web apps.

      • App Check does not support web apps that serve on more than 250 domains.

      • Never add localhost as a domain to a reCAPTCHA key that is deployed to (or is going to be deployed to) production.

      • Leave the "Use checkbox challenge" option unselected.

      For detailed instructions, see Create score-based reCAPTCHA keys.

    4. Take note of each key. You'll need to add them into the registration flow in the Firebase console.

  3. In the Firebase console, navigate to Security > App Check.

  4. In the Apps tab, register each of your target platform apps to use App Check with the reCAPTCHA Enterprise provider. You'll need to provide the key you got in the Google Cloud console.

  5. Optional: Set the token time to live (TTL).

    In the app registration settings, set a custom time to live (TTL) for App Check tokens issued by the provider. You can set the TTL to any value between 30 minutes and 7 days. When changing this value, be aware of the following tradeoffs:

    • Security: Shorter TTLs provide stronger security, because it reduces the window in which a leaked or intercepted token can be abused by an attacker.
    • Performance: Shorter TTLs mean your app will perform attestation more frequently. Because the app attestation process adds latency to network requests every time it's performed, a short TTL can impact the performance of your app.
    • Quota and cost: Shorter TTLs and frequent re-attestation deplete your quota faster, and for paid services, potentially cost more. See Quotas & limits.

    The default TTL of 1 hour is reasonable for most apps. Note that the App Check library refreshes tokens at approximately half the TTL duration.

  6. Optional: Configure advanced settings.

  7. Click Save.

(Optional) Configure advanced settings

When a user opens your app, reCAPTCHA Enterprise evaluates the level of risk the user interaction under the key poses, and returns a score between 0.0 and 1.0, in increments of 0.1.

  • A score of 0.0 indicates that the interaction poses high risk and might be fraudulent.
  • A score of 1.0 indicates that the interaction poses low risk and is very likely legitimate.

App Check lets you configure an app risk threshold so you can adjust your tolerance for this risk.

For most use cases, the default threshold value of 0.5 is recommended. If your use case requires adjustment, you can configure this value for each of your apps in the Firebase console (go to Security > App Check). Make sure to expand and review some important considerations about configuring the app risk threshold below.

2. Add the App Check plugin to your app

To use the reCAPTCHA Enterprise provider, you must add the corresponding App Check plugin.

  1. From the root of your Flutter project, run the following command to install the plugin:

    flutter pub add firebase_app_check

  2. Once complete, rebuild your Flutter project:

    flutter run

3. Initialize App Check

In your app, you need to initialize App Check before you use any other Firebase services.

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_app_check/firebase_app_check.dart';
import 'firebase_options.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  await FirebaseAppCheck.instance.activate(
    providerWeb: ReCaptchaEnterpriseProvider(WEB_SITE_KEY),
    providerAndroid: const AndroidReCaptchaProvider(ANDROID_SITE_KEY),
    providerApple: const AppleReCaptchaProvider(IOS_SITE_KEY),
  );
  runApp(App());
}

4. Monitor metrics and enable enforcement

After you've set up App Check in your app, start distributing the updated app to your users.

The updated client app will begin sending App Check tokens along with every request it makes to Firebase. However, App Check won't block requests with invalid tokens until App Check is enforced.

Monitor metrics

Before you enable enforcement, make sure that doing so won't disrupt your existing legitimate users. However, if you're seeing suspicious use of your app resources, you might want to enable enforcement sooner.

To help make this decision, you can review App Check metrics for the services you use:

Enable App Check enforcement

When you understand how App Check will affect your users and you're ready to proceed, you can enable App Check enforcement:

Use App Check in debug environments

App Check classifies some environments as invalid, such as requests from an emulator / simulator or localhost during development or from a continuous integration (CI) environment.

To run your app in these types of environments after App Check is enforced, you need to create a debug build of your app that uses the App Check debug provider instead of a production attestation provider.

For more details, see Use App Check with the debug provider in Flutter apps.

Pricing

App Check creates an assessment on your behalf to validate the user's response token each time your app refreshes its App Check token. Your Firebase project will be charged for each assessment created above the no-cost quota. For details, see reCAPTCHA pricing.

By default, your app will refresh this token twice every 1 hour. To control how frequently your app refreshes App Check tokens (and thus how frequently new assessments are created), you can configure the token TTL.