此页面由 Cloud Translation API 翻译。

将 reCAPTCHA Enterprise 与 iOS 应用集成

本页介绍了如何在您的 iOS 应用中集成 reCAPTCHA Enterprise。

由于移动设备在屏幕尺寸、性能和应用界面方面存在差异，因此视觉复选框 reCAPTCHA 验证（我不是机器人）不适用于 iOS 移动应用。您可以改为实施自己的分层强制执行策略（例如 MFA 流程），为可疑流量提供替代兑换路径。

准备工作

将应用的最低 SDK 设置为 iOS 11，或创建新的移动应用。
为 reCAPTCHA Enterprise 准备好环境。
为 iOS 应用平台创建 reCAPTCHA 密钥。

或者，您可以通过执行以下任一步骤来复制适用于 iOS 的现有 reCAPTCHA 密钥的 ID：
- 如需从 Google Cloud 控制台复制现有密钥的 ID，请执行以下操作：
  1. 转到 reCAPTCHA Enterprise 页面。
    
    转到 reCAPTCHA Enterprise
  2. 在 reCAPTCHA 密钥列表中，将指针悬停在要复制的密钥上，然后点击。
- 如需使用 REST API 复制现有密钥的 ID，请使用 projects.keys.list 方法。
- 如需使用 gcloud CLI 复制现有密钥的 ID，请使用 gcloud recaptcha keys list 命令。
拥有 GitHub 帐号。
阅读 Apple 隐私权详细信息。

准备 iOS 环境

如需准备开发环境，请执行以下操作：

下载并安装最新版本的 Xcode，然后创建一个新的空白 iOS 单视图应用。
使用以下其中一种方法下载 SDK：
CocoaPods
1. 下载并安装 CocoaPods。
2. 创建一个 Podfile，并将以下几行代码添加到您的 Podfile：
```
source "https://github.com/CocoaPods/Specs.git"

target 'AppTarget' do

  # Podfiles must include use_frameworks! or
  # use_frameworks! :linkage => :static
  use_frameworks!

  pod "RecaptchaEnterprise", "18.5.0-beta02"
  ...

end
```
3. 运行 pod update 以安装所需的依赖项。
  
  注意：运行 pod clone 不会安装所需的依赖项。
Swift Package Manager
1. 在 XCode 中，依次选择 File > Add Packages，然后在 Search 或 Enter Package 网址 字段中输入以下网址：https://github.com/GoogleCloudPlatform/recaptcha-enterprise-mobile-sdk
2. 在 XCode 对话框中，输入以下详细信息：
  - GitHub 用户名。
  - 您按照 GitHub 的说明创建的个人访问令牌。个人访问令牌必须具有 XCode 登录对话框中列出的范围。
  Xcode 会安装 SDK 及其所需的依赖项。
Flutter
如需详细了解如何通过 Flutter 使用 reCAPTCHA Enterprise，请参阅 Flutter 文档。

ReactNative
如需详细了解如何通过 React Native 使用 reCAPTCHA Enterprise，请参阅 React Native 文档。
直接下载
1. 如果要将 SDK 及其依赖项下载为 xcframeworks，请下载客户端。
  
  注意：请将所有二进制文件添加为静态 xcframeworks。

配置应用

您可以使用 Swift 或 Objective-C 编写应用。

如需配置您的应用，请在您的应用中添加以下文件：

Swift

如果您的应用是用 Swift 编写的，请创建一个 Objective-C 迁移桥头，并包含以下导入：
```
#import <RecaptchaEnterprise/RecaptchaEnterprise.h>
```

Objective-C

如果您的应用是用 Objective-C 编写的，请创建一个虚拟 Swift 文件，并添加以下导入内容，以确保 Xcode 可以找到并关联 Swift 库。
```
import Foundation
```
如需确保正确链接 Swift 代码，请依次点击 Target > Build Settings > Always Embed Swift Standard Libraries，并验证该选项是否设置为 Yes。

将 reCAPTCHA Enterprise 与您的 iOS 应用集成

要将 reCAPTCHA Enterprise 与您的 iOS 应用集成，请在 Xcode 中执行以下步骤：

如需使用您创建的 reCAPTCHA 密钥 (KEY_ID) 实例化 SDK，请使用以下代码更新应用：

Swift with Storyboard

更新 ViewController.swift。

如果您使用的是 CocoaPods，请忽略 import RecaptchaEnterprise 行，因为 *-Bridging-Header.h 文件中的 import 语句 #import <RecaptchaEnterprise/RecaptchaEnterprise.h> 已经足够。

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

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

如果应用的最低操作系统版本低于 13，请改用尾随闭包：

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

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

Swift 和 SwiftUI

创建 ViewModel 类。

import RecaptchaEnterprise

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

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

如果应用的最低操作系统版本低于 13，请改用尾随闭包：

import RecaptchaEnterprise

class ViewController: UIViewController {
  var recaptchaClient: RecaptchaClient?

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

在 ContentView.swift 中实例化 ViewModel。

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

更新 ViewController.h。

#import <RecaptchaEnterprise/RecaptchaEnterprise.h>

@interface ViewController : UIViewController
@property (strong, atomic) RecaptchaClient *recaptchaClient;
@end

更新 ViewController.m。

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

创建一个按钮，用于调用 reCAPTCHA Enterprise 并触发 execute()。

Swift with Storyboard

在分镜脚本中，创建一个按钮。
在 ViewController 中创建与您创建的按钮关联的操作。

使用以下代码段调用传递 Login 操作的 execute() 方法，以返回 reCAPTCHA 令牌：

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)
  }
}

如果应用的最低操作系统版本低于 13，请改用尾随闭包：

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 和 SwiftUI

使用执行代码更新 ViewModel.swift：

import RecaptchaEnterprise

@MainActor class ViewModel: ObservableObject {

  func execute() {
    guard let recaptchaClient = 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)
      }
    }
  }
}

如果应用的最低操作系统版本低于 13，请改用尾随闭包：

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)
  }
}

更新 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

在故事板中，创建一个按钮。
在 ViewController 中创建与您创建的按钮关联的操作。

使用以下代码段调用传递 Login 操作的 execute() 方法，以返回 reCAPTCHA 令牌：

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);
}];

测试您的应用：
1. reCAPTCHA Enterprise 使用 Apple 的 AppAttest 作为其检测引擎的一部分。如果您不打算使用具有固定得分的测试密钥进行本地开发，请执行以下操作：
  1. 在 Xcode 中，将 App Attest 功能添加到您的应用中。
  2. 在项目的 .entitlements 文件中，将 App Attest 环境设置为 production。
2. 如需清理 Xcode 构建环境，请在 Product 菜单中点击 Clean Build Folder。
3. 如需运行应用，请在 Product 菜单中点击 Run。
4. 在加载的应用中，点击您之前创建的按钮。
5. 观察调试输出窗口，如果集成正确完成，将返回一个 reCAPTCHA 令牌（字母数字字符串）。

设置 API 调用超时

您可以使用每个 API 的 withTimeout 属性，为 getClient 和 execute API 指定超时值。

Swift

调用 getClient 时设置超时。

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

如果您的应用的最低操作系统版本低于 13，请改用尾随闭包：

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

调用 execute 时设置超时。

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

如果您的应用的最低操作系统版本低于 13，请改用尾随闭包：

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

Objective-C

调用 getClient 时设置超时。

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

调用 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 参考文档

如需查看 iOS 版 reCAPTCHA API 的完整参考文档，请参阅 RecaptchaEnterprise。

后续步骤

要评估 reCAPTCHA 响应令牌，请创建评估。

注意：reCAPTCHA 响应令牌是通过后端服务器（而非移动设备）评估和注释的。

将 reCAPTCHA Enterprise 与 iOS 应用集成

准备工作

准备 iOS 环境

CocoaPods

Swift Package Manager

Flutter

ReactNative

直接下载

配置应用

Swift

Objective-C

将 reCAPTCHA Enterprise 与您的 iOS 应用集成

Swift with Storyboard

Swift 和 SwiftUI

Objective-C

Swift with Storyboard

Swift 和 SwiftUI

Objective-C

设置 API 调用超时

Swift

Objective-C

API 参考文档

后续步骤