This page explains how to integrate reCAPTCHA Enterprise in your iOS app. Due to the variation in mobile devices in terms of screen size, performance, and UIs of the apps, the visual checkbox reCAPTCHA challenge (I'm not a robot) is not available for mobile apps. You can instead implement your own tiered enforcement strategy, such as an MFA flow to provide an alternative redemption path for suspicious traffic.
Before you begin
Set the minimum SDK of your app to iOS 14 or create a new mobile app.
Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.
Create a reCAPTCHA key for the iOS app platform.
Have a GitHub account.
Read the Apple privacy details.
Prepare your environment
To prepare your development environment, do the following:
Download and install the latest version of Xcode and create a new blank iOS single view application {: .extern}.
Download the SDK using direct download, CocoaPods or Swift Package Manager.
CocoaPods
- Download and install CocoaPods.
Create a Podfile and add the following lines to your Podfile:
source "https://github.com/CocoaPods/Specs.git" pod "RecaptchaEnterprise", "18.0.3"
Install the required dependencies by running
pod update
.
Swift Package Manager
- In XCode, select File > Add Packages, and enter the
following URL in the Search or Enter Package URL field:
https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk
In the XCode dialog, enter the following details:
- GitHub username.
- A personal access token that you created using GitHub's instructions. The Personal Access Token must have the scopes listed in the XCode Sign In dialog.
Xcode installs the SDK and its required dependencies.
Direct download
If you want to download the SDK and its dependencies as xcframeworks, download the client
Configure the app
You can write your apps in Swift or Objective-C. To configure your app, do the following:
Add the following files in your apps:
Swift
If your app is written in Swift, create an Objective-C bridging header and include the following import:
#import <RecaptchaEnterprise/RecaptchaEnterprise.h>
Ensure that
-ObjC
is listed on your linker flags. Navigate to Target > Build Settings > All > Linking and verify thatOther Linker Flags
shows-ObjC
.
Objective-C
If your app is written in Objective-C, create a dummy Swift file and include the following import to make sure Xcode can find and link the Swift libraries.
import Foundation
To ensure that the
Swift
code is linked correctly navigate to Target > Build Settings > Always Embed Swift Standard Libraries and verify that the option is set toYes
.
Integrate reCAPTCHA Enterprise with your iOS app
To integrate reCAPTCHA Enterprise with your iOS app, follow these steps in Xcode:
To instantiate the SDK with the reCAPTCHA key that you created, update the app with the following code:
Swift with Storyboard
- Update
ViewController.swift
.
If you are using CocoaPods, then ignore the
import RecaptchaEnterprise
line, because the import statement#import <RecaptchaEnterprise/RecaptchaEnterprise.h>
in the*-Bridging-Header.h
file is sufficient.For iOS 14 or higher:
import RecaptchaEnterprise class ViewController: UIViewController { var recaptchaClient: RecaptchaClient? override func viewDidLoad() { super.viewDidLoad() Task { let (recaptchaClient, error) = await Recaptcha.getClient( siteKey: "reCAPTCHA_KEY_iOS") if let recaptchaClient = recaptchaClient { self.recaptchaClient = recaptchaClient } if let error = error { print("RecaptchaClient creation error: \(error.errorMessage).") } } } }
For iOS 12 or higher:
import RecaptchaEnterprise class ViewController: UIViewController { var recaptchaClient: RecaptchaClient? override func viewDidLoad() { super.viewDidLoad() Task { if #available(iOS 14.0, *) { let (recaptchaClient, error) = await Recaptcha.getClient( siteKey: "reCAPTCHA_KEY_iOS") if let recaptchaClient = recaptchaClient { self.recaptchaClient = recaptchaClient } if let error = error { print("RecaptchaClient creation error: \(error.errorMessage).") } } } } }
Swift with SwiftUI
Create a
ViewModel
class.If you're using CocoaPods, then ignore the
import RecaptchaEnterprise
line, because the import statement#import <RecaptchaEnterprise/RecaptchaEnterprise.h>
in the*-Bridging-Header.h
file is sufficient.- For iOS 14 or higher:
import RecaptchaEnterprise @MainActor class ViewModel: ObservableObject { private var recaptchaClient: RecaptchaClient? init() { Task { let (recaptchaClient, error) = await Recaptcha.getClient( siteKey: "reCAPTCHA_KEY_iOS") if let recaptchaClient = recaptchaClient { self.recaptchaClient = recaptchaClient } if let error = error { print("RecaptchaClient creation error: \(error.errorMessage).") } } } }
- For iOS 12 or higher:
import RecaptchaEnterprise @MainActor class ViewModel: ObservableObject { private var recaptchaClient: RecaptchaClient? init() { Task { if #available(iOS 14.0, *) { let (recaptchaClient, error) = await Recaptcha.getClient( siteKey: "reCAPTCHA_KEY_iOS") if let recaptchaClient = recaptchaClient { self.recaptchaClient = recaptchaClient } if let error = error { print("RecaptchaClient creation error: \(error.errorMessage).") } } } } }
Instantiate
ViewModel
inContentView.swift
.import SwiftUI import RecaptchaEnterprise struct ContentView: View { @StateObject private var viewModel = ViewModel() var body: some View { } } struct ContentView_Previews: PreviewProvider { static var previews: some View { ContentView() } }
Objective-C
Update
ViewController.h
.#import <RecaptchaEnterprise/RecaptchaEnterprise.h> @interface ViewController : UIViewController @property (strong, atomic) RecaptchaClient *recaptchaClient; @end
Update
ViewController.m
.@implementation ViewController [Recaptcha getClientWithSiteKey:@"reCAPTCHA_KEY_iOS" completionHandler:^void(RecaptchaClient* recaptchaClient, RecaptchaError* error) { if (!recaptchaClient) { NSLog(@"%@", error.errorMessage); return; } self->_recaptchaClient = recaptchaClient; } ]; @end
- Update
Create a button to call reCAPTCHA Enterprise and trigger
execute()
.Swift with Storyboard
- In the storyboard, create a button.
- Create an action in
ViewController
linked to the button that you created. Call the
execute()
method passing aLogin
action to return a reCAPTCHA token by using the following code snippet:guard let recaptchaClient = recaptchaClient else { print("RecaptchaClient creation failed.") return } Task { let (token, error) = await recaptchaClient.execute(RecaptchaAction(action: .login)) if let token = token { print(token.recaptchaToken) } else { print(error?.errorMessage) } }
Swift with SwiftUI
Update ViewModel.swift with the following code:
import RecaptchaEnterprise @MainActor class ViewModel: ObservableObject { private var recaptchaClient: RecaptchaClient? init() { Task { let (recaptchaClient, error) = await Recaptcha.getClient( siteKey: "reCAPTCHA_KEY_iOS") if let recaptchaClient = recaptchaClient { self.recaptchaClient = recaptchaClient } if let error = error { print("RecaptchaClient creation error: \(error.errorMessage).") } } } func execute() { guard let client = self.recaptchaClient else { print("Client not initialized correctly.") return } Task { let (token, error) = await client.execute( RecaptchaAction(action: .login)) if let token = token { print(token.recaptchaToken) } else { print(error?.errorMessage) } } } }
Update ContentView.swift.
import SwiftUI import RecaptchaEnterprise struct ContentView: View { @StateObject private var viewModel = ViewModel() var body: some View { Button { viewModel.execute() } label: { Text("Execute") }.padding() Spacer() } } struct ContentView_Previews: PreviewProvider { static var previews: some View { ContentView() } }
Objective-C
- In the storyboard, create a button.
- Create an action in
ViewController
linked to the button that you created. Call the
execute()
method passing aLogin
action to return a reCAPTCHA token by using the following code snippet:if (!self->_recaptchaClient) { return; } [recaptchaClient execute:[[RecaptchaAction alloc] initWithAction: RecaptchaActionTypeLogin] completionHandler:^void(RecaptchaToken* _Nullable token, RecaptchaError* _Nullable error) { if (!token) { NSLog (@"%@", error.errorMessage); return; } NSLog (@"%@", token); }];
Test your application:
reCAPTCHA Enterprise uses Apple's AppAttest as part of its detection engine. If you don't plan to use a testing key with a fixed score for local development, do the following:
In Xcode, add the App Attest capability to your app.
In your project's
.entitlements
file, set the App Attest environment toproduction
.
To clean your Xcode build environment, in the Product menu, click Clean Build Folder.
To run the application, in the Product menu, click Run.
In your loaded application, click the button that you created earlier.
Observe your debug output window for a reCAPTCHA token (alpha-numeric string), which is returned if the integration is successful.
What's next
- To assess the reCAPTCHA response token, create an assessment.