Get started using App Check with reCAPTCHA Enterprise on Apple platforms

Select platform:

iOS+ Android Web Flutter

This page shows you how to set up App Check in an Apple platforms 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

If you haven't already, add Firebase to your Apple project.
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 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.
  For detailed instructions, see Create score-based reCAPTCHA keys.
4. Take note of this key. You'll need to add it into the registration flow in the Firebase console.
In the Firebase console, navigate to Security > App Check.
In the Apps tab, register your Apple 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.

Important: Make sure to register all of your project's apps with an attestation provider (like reCAPTCHA Enterprise). Once you enable enforcement for a service, only registered apps will be able to access the service.
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.
Optional: Configure advanced settings.
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.

View important considerations about app risk threshold

App Check uses your configured app risk threshold as the minimum reCAPTCHA Enterprise score required for a user interaction to be deemed legitimate. All reCAPTCHA Enterprise scores strictly less than your configured threshold will be rejected. When adjusting your app risk threshold, be aware of the following:

If your Firebase project is on the no-cost Spark pricing plan, then out of the 11 possible reCAPTCHA Enterprise score levels, only the following four score levels are available: 0.1, 0.3, 0.7, and 0.9.

During this time, App Check will correspondingly only allow app risk threshold values of 0.1, 0.3, 0.5, 0.7, and 0.9. An app risk threshold value of 0.5 is still recommended for most use cases.
- To enable all 11 reCAPTCHA Enterprise score levels, link a Cloud Billing account to your project (which means you upgrade your Firebase project to the pay-as-you-go Blaze pricing plan). Once you've upgraded your project, App Check will let you configure any app risk threshold values between 0.0 and 1.0, in increments of 0.1.
  
  Note: After a Cloud Billing account is linked to your project, an automatic security review is triggered for your project. For more information, see the reCAPTCHA Enterprise documentation.
To monitor the distribution of high and low reCAPTCHA Enterprise scores for your app, go to the reCAPTCHA Enterprise page in the Google Cloud console, and select the key used by your app.
Set your app risk threshold appropriately for your tolerance:
- If you have high app risk tolerance, move the slider to the right to decrease the app risk threshold.
  - A value of 0.0 is not recommended, as this setting disables abuse protection.
- If you have low app risk tolerance, move the slider to the left to increase the app risk threshold.
  - A value of 1.0 is not recommended, as this setting can also potentially deny access for legitimate users who don't meet this high trust threshold.
  Warning: To avoid disrupting your legitimate users, gradually increase the app risk threshold when App Check is enforced. Always monitor App Check request metrics to verify that traffic has not been disrupted.

For additional details, review the reCAPTCHA Enterprise documentation.

2. Add the App Check SDK to your app

Use Swift Package Manager (SPM) to install and manage Firebase dependencies. If you're already using Firebase, then make sure your Firebase package is v12.17.0 or later.

In Xcode, open your app project.
Add the Firebase library:
1. Navigate to File > Add Packages.
2. When prompted, add the Firebase Apple platforms SDK repository:
```
https://github.com/firebase/firebase-ios-sdk
```
3. Select the latest SDK version (v12.17.0 or later).
4. Select the FirebaseAppCheck library.
5. Click Add Package. Xcode will resolve and download the dependencies.
6. When prompted, add the library to your app target.
Add the reCAPTCHA Enterprise library:
1. Navigate back to File > Add Packages
2. When prompted, add the reCAPTCHA Enterprise SDK repository:
```
https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk
```
3. Select the RecaptchaEnterprise library.
4. Click Add Package. When prompted, add the library to your app target.

3. Initialize App Check

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

Create an instance of RecaptchaProviderFactory, passing in your reCAPTCHA key, and then configure App Check to use it:

let providerFactory = RecaptchaProviderFactory(siteKey: "SITE_KEY")
AppCheck.setAppCheckProviderFactory(providerFactory)

FirebaseApp.configure()

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:

Monitor App Check request metrics for Firebase AI Logic, SQL Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity for iOS, Maps JavaScript API, and Places API (New).
Monitor App Check request metrics for Cloud Functions.

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:

Enable App Check enforcement for Firebase AI Logic, SQL Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity for iOS, Maps JavaScript API, and Places API (New).
Enable App Check enforcement for Cloud Functions.

Use App Check in debug environments

App Check classifies some environments as invalid, such as requests from an emulator / simulator 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 on Apple platforms.

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.