Integrating reCAPTCHA Enterprise with iOS apps

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 11 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
1. Download and install CocoaPods.
2. Create a Podfile and add the following lines to your Podfile:
```
source "https://github.com/CocoaPods/Specs.git"

pod "RecaptchaEnterprise", "18.2.0"
```
3. Install the required dependencies by running pod update.
  
  Note: Running pod clone doesn't install the required dependencies.
Swift Package Manager
1. 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
2. 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
1. If you want to download the SDK and its dependencies as xcframeworks, download the client
  
  Note: Add all binaries as static xcframeworks.

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
1. If your app is written in Swift, create an Objective-C bridging header and include the following import:
```
#import <RecaptchaEnterprise/RecaptchaEnterprise.h>
```
2. Ensure that -ObjC is listed on your linker flags. Navigate to Target > Build Settings > All > Linking and verify that Other Linker Flags shows -ObjC.
Objective-C
1. 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
```
2. 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 to Yes.

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.

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

  override func viewDidLoad() {
    super.viewDidLoad()
    Task {
      do {
        let client = try await Recaptcha.getClient(withSiteKey: "reCAPTCHA_KEY_iOS")
        self.recaptchaClient = client
      } catch let error as RecaptchaError {
         print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
      }
    }
  }
}

If your application's minimum OS version is less than 13, use a trailing closure instead:

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

  override func viewDidLoad() {
    super.viewDidLoad()
    Recaptcha.getClient(withSiteKey: "reCAPTCHA_KEY_iOS") { client, error in
      guard let client = client else {
          print("RecaptchaClient creation error: \(error).")
        return
      }
      self.recaptchaClient = client
    }
  }
}

Swift with SwiftUI

Create a ViewModel class.

If you're using CocoaPods, then ignore theimport RecaptchaEnterprise line, because the import statement #import <RecaptchaEnterprise/RecaptchaEnterprise.h> in the *-Bridging-Header.h file is sufficient.

import RecaptchaEnterprise

@MainActor class ViewModel: ObservableObject {
  private var recaptchaClient: RecaptchaClient?

  init() {
     Task {
      do {
        let client = try await Recaptcha.getClient(withSiteKey: "reCAPTCHA_KEY_iOS")
        self.recaptchaClient = client
      } catch let error as RecaptchaError {
         print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
      }
    }
  }
}

If your application's minimum OS version is less than 13, use a trailing closure instead:

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

  override func viewDidLoad() {
    super.viewDidLoad()
    Recaptcha.getClient(withSiteKey: "reCAPTCHA_KEY_iOS") { client, error in
      guard let client = client else {
          print("RecaptchaClient creation error: \(error).")
        return
      }
      self.recaptchaClient = client
    }
  }
}

Instantiate ViewModel in ContentView.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"
      completion:^void(RecaptchaClient* recaptchaClient, NSError* error) {
        if (!recaptchaClient) {
          NSLog(@"%@", (RecaptchaError *)error.errorMessage);
          return;
        }
        self->_recaptchaClient = recaptchaClient;
      }
];
@end

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 a Login action to return a reCAPTCHA token by using the following code snippet:

guard let recaptchaClient = recaptchaClient else {
  print("RecaptchaClient creation failed.")
  return
}
Task {
  do {
    let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
    print(token)
  } catch let error as RecaptchaError {
    print(error.errorMessage)
  }
}

If your application's minimum OS version is less than 13, use a trailing closure instead:

guard let recaptchaClient = recaptchaClient else {
  print("RecaptchaClient creation failed.")
  return
}
recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
  if let token = token {
    print(token)
  } else {
    print(error)
  }
}

Swift with SwiftUI

Update ViewModel.swift with the execute code:

import RecaptchaEnterprise

@MainActor class ViewModel: ObservableObject {

  func execute() {
    guard let client = self.recaptchaClient else {
      print("Client not initialized correctly.")
      return
    }

    Task {
      do {
        let token = try await recaptchaClient.execute(withAction: RecaptchaAction.login)
        print(token)
      } catch let error as RecaptchaError {
        print(error.errorMessage)
      }
    }
  }
}

If your application's minimum OS version is less than 13, use a trailing closure instead:

guard let recaptchaClient = recaptchaClient else {
  print("RecaptchaClient creation failed.")
  return
}
recaptchaClient.execute(withAction: RecaptchaAction.login) { token, error in
  if let token = token {
    print(token)
  } else {
    print(error)
  }
}

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 a Login action to return a reCAPTCHA token by using the following code snippet:

if (!self->_recaptchaClient) {
  return;
}

[recaptchaClient execute:RecaptchaAction.login
    completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
  if (!token) {
    NSLog (@"%@", (RecaptchaError *)error.errorMessage);
    return;
  }
  NSLog (@"%@", token);
}];

Test your application:
1. 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:
  1. In Xcode, add the App Attest capability to your app.
  2. In your project's .entitlements file, set the App Attest environment to production.
2. To clean your Xcode build environment, in the Product menu, click Clean Build Folder.
3. To run the application, in the Product menu, click Run.
4. In your loaded application, click the button that you created earlier.
5. Observe your debug output window for a reCAPTCHA token (alpha-numeric string), which is returned if the integration is successful.

Set a timeout for API calls

You can specify a timeout value for getClient and execute APIs by using the withTimeout property of each API.

Swift

Set timeout when calling getClient.

    Task {
      do {
        self.recaptchaClient = try await Recaptcha.getClient(
          withSiteKey: "reCAPTCHA_KEY_iOS",
          withTimeout: 15000
        )
      } catch let error as RecaptchaError {
          print("RecaptchaClient creation error: \(String(describing: error.errorMessage)).")
      }
    }

If your application's minimum OS version is less than 13, use a trailing closure instead:

  Recaptcha.getClient(
    withSiteKey: "reCAPTCHA_KEY_iOS",
    withTimeout: 15000
  ) { client, error in
    guard let client = client else {
        print("RecaptchaClient creation error: \(error).")
      return
    }
    self.recaptchaClient = client
  }

Set timeout when calling execute.

  Task {
    do {
      let token = try await recaptchaClient.execute(
        withAction: RecaptchaAction.login,
        withTimeout: 10000)
      print(token)
    } catch let error as RecaptchaError {
      print(error.errorMessage)
    }
  }

If your application's minimum OS version is less than 13, use a trailing closure instead:

  recaptchaClient.execute(
    withAction: RecaptchaAction.login,
    withTimeout: 10000
  ) { token, error in
    if let token = token {
      print(token)
    } else {
      print(error)
    }
  }

Objective-C

Set timeout when calling getClient.

  [Recaptcha getClientWithSiteKey:@"reCAPTCHA_KEY_iOS"
              withTimeout:15000.0
               completion:^void(RecaptchaClient *recaptchaClient, NSError *error) {
                 if (!recaptchaClient) {
                   NSLog(@"%@", (RecaptchaError *)error.errorMessage);
                   return;
                 }
                 self->_recaptchaClient = recaptchaClient;
               }];

Set timeout when calling execute.

  [recaptchaClient execute:RecaptchaAction.login
      witTimeout:10000.0
      completion:^void(NSString* _Nullable  token, NSError* _Nullable error) {
    if (!token) {
      NSLog (@"%@", (RecaptchaError *)error.errorMessage);
      return;
    }
    NSLog (@"%@", token);
  }];

API reference

For a complete reference of the reCAPTCHA API for iOS, see RecaptchaEnterprise.

What's next

To assess the reCAPTCHA response token, create an assessment.
To provide feedback on the accuracy of the created assessment, annotate an assessment.

Note: reCAPTCHA response tokens are assessed and annotated from your backend server, not from the mobile device.

Integrating reCAPTCHA Enterprise with iOS apps

Before you begin

Prepare your environment

CocoaPods

Swift Package Manager

Direct download

Configure the app

Swift

Objective-C

Integrate reCAPTCHA Enterprise with your iOS app

Swift with Storyboard

Swift with SwiftUI

Objective-C

Swift with Storyboard

Swift with SwiftUI

Objective-C

Set a timeout for API calls

Swift

Objective-C

API reference

What's next