HCaptcha 2.8.0

HCaptcha 2.8.0

×

由 hCaptcha Dev 维护。

HCaptcha 2.8.0

HCaptcha

Carthage compatible Version Platform Requirements Swift Package Manager compatible Build

将 hCaptcha 添加到您的项目中。这个库可以自动处理 hCaptcha 的事件并返回验证令牌，如果需要，将通过模态对话框展示挑战。

警告⚠️

为了确保您的应用程序安全，您需要将在这里收到的令牌发送到您的后端，并通过 api.hcaptcha.com/siteverify 端点进行服务器端验证。

安装

HCaptcha 通过 CocoaPods、Carthage 和 SPM (Swift Package Manager) 提供。

要安装它，只需将以下行添加到依赖文件中：

Cocoapods

pod "HCaptcha"
# or
pod "HCaptcha/RxSwift"

Carthage

github "hCaptcha/HCaptcha-ios-sdk"

Carthage 将创建两个不同的框架，分别命名为 HCaptcha 和 HCaptcha_RxSwift，后者包含 HCaptcha 框架的 RxSwift 扩展。

已知问题

  • Carthage 不支持预先构建的 zips 用于 xcframework，因此请使用 --no-use-binaries - Carthage/Carthage#3130
  • Carthage 有一个 RxSwift 构建问题，也可以通过 --no-use-binaries 来避免 - Carthage/Carthage#3243

SPM

标准 SPM 公式：使用 Package.swift

需求

平台 需求
iOS ✅ >= 9.0
WatchOS ✖️

用法

hCaptcha站点的密钥可以作为Info.plist密钥指定，也可以在实例化HCaptcha时作为参数传递。

对于Info.plist配置，请在您的Info.plist中添加HCaptchaKey（站钥）和HCaptchaDomain（带协议，即https://）。

  • HCaptchaKey是您的hCaptcha站钥。
  • HCaptchaDomain应是一个像https://www.your.com这样的字符串。
  • 如果指定了baseURL，则应与HCaptchaDomain匹配；它控制初始化hCaptcha会话时使用的URI。例如：https://www.your.com

设置了这些值后，运行

let hcaptcha = try? HCaptcha()

override func viewDidLoad() {
    super.viewDidLoad()

    hcaptcha?.configureWebView { [weak self] webview in
        webview.frame = self?.view.bounds ?? CGRect.zero
    }
}


func validate() {
    hcaptcha?.validate(on: view) { [weak self] (result: HCaptchaResult) in
        print(try? result.dematerialize())
    }
}

注意：如果您需要将hCaptcha显示在UIVisualEffectView上方，请确保传递visualEffectView.contentView而不是visualEffectView。根据Apple的文档

您将效果视图添加到视图层次结构后，请将任何子视图添加到效果视图的内容视图属性。不要直接将子视图添加到效果视图本身。

更多详情在这里。

如果您 prefer 将信息保留在Info.plist之外，则可以使用：

let hcaptcha = try? HCaptcha(
    apiKey: "YOUR_HCAPTCHA_KEY", 
    baseURL: URL(string: "YOUR_HCAPTCHA_DOMAIN")!
)

...

注意：在大多数情况下，baseURL可以是https://

您还可以安装反应性子pod，并使用RxSwift。

hcaptcha.rx.validate(on: view)
    .subscribe(onNext: { (token: String) in
        // Do something
    })

注意：调用者代码负责在挑战处理完毕后隐藏WebView。这在示例应用程序中进行了演示，并可以使用以下方法完成：

  1. 普通Swift API

    ...
var captchaWebView: WKWebView?
...

hcaptcha?.configureWebView { [weak self] webview in
    self?.captchaWebView = webview
}
...

hcaptcha.validate(on: view) { result in
    ...

    captchaWebView?.removeFromSuperview()
}

  2. （有关更多信息，请参阅示例）

    ...
hcaptcha?.configureWebView { [weak self] webview in
    webview.tag = "hCaptchaViewTag"
}
...

let disposeBag = DisposeBag()
let validate = hcaptcha.rx.validate(on: view)
...

validate
    .map { [weak self] _ in
        self?.view.viewWithTag("hCaptchaViewTag")
    }
    .subscribe(onNext: { webview in
        webview?.removeFromSuperview()
    })
    .disposed(by: disposeBag)

设置主机重写（可选）

由于此SDK使用本地HTML文件，您可能需要设置主机重写，以更好地跟踪和实施siteverify参数。

您可以通过传递额外的参数host来实现。

let hcaptcha = try? HCaptcha(
    ...
    host: "your-domain.com",
    ...
)

...

注意：这应该是纯粹的**主机**，即不包含协议前缀，例如https://。

更改小部件主题

SDK 支持三种内置主题：light（浅色）、dark（暗色）和 contrast（对比度）。

let hcaptcha = try? HCaptcha(
    ...
    theme: "dark", // "light" or "contrast"
    ...
)

...

对于企业版 sitekeys，我们还支持通过 customTheme 参数自定义主题，具体描述如下。

备用端点（可选）

如果您是具有第一方托管访问权限的企业用户，可以使用自己的端点（例如 verify.your.com）。

然后您可以在代码中启用它

let hcaptcha = try? HCaptcha(
    ...
    endpoint: URL("https://custom.endpoint")!,
    ...
)

...

企业版更多参数（可选）

企业版参数如下

  • rqdata（字符串）
  • reportapi（字符串）
  • assethost（字符串）
  • imghost（字符串）
  • sentry（布尔值）
  • customTheme（JS对象或JSON的字符串表示；请参阅企业版文档）

可通过 HCaptcha(...) 传递

请查阅 hCaptcha 企业版文档 了解更多详细信息。

启用可见复选框流程

此 iOS SDK 默认假定您想要一个“不可见”的复选框，即从您的应用内触发 hCaptcha 流程应返回令牌或直接向用户显示挑战。

如果您希望有经典的“标准”或“紧凑”复选框行为，即显示可勾选的复选框，然后在关闭或显示挑战之前勾选，可以将 size 传递给 HCaptcha 初始化程序。

let hcaptcha = try? HCaptcha(size: .compact)

您现在将获得所需的行为。

使用横置而非竖置方向

orientation参数可以设置为.portrait或.landscape横置方向以调整挑战窗口的行为。

let hcaptcha = try? HCaptcha(orientation: .landscape)

默认情况下，方向为竖置且不会重新排版。

但是，如果你有一个专用于横置模式的应用程序（例如游戏），也可以将挑战UI设置为与这种设计选择匹配。

SDK事件

此SDK允许您通过onEvent方法接收交互事件，通过您的分析。目前SDK支持

  • open在hCaptcha被打开并且挑战对应用程序用户可见时触发
  • expired在通行码响应过期用户必须重新验证时触发
  • challengeExpired在用户显示的挑战超时且没有答案时触发
  • close在用户关闭挑战时触发
  • error在挑战验证过程中发生内部错误时触发，例如网络错误。错误详细信息将通过data参数提供，如下例所示。注意：此事件并非用于错误处理，仅为分析目的。对于错误处理，请参阅validate API调用的文档。

您可以使用以下代码实现此功能

let hcaptcha = try? HCaptcha(...)
...
hcaptcha.onEvent { (event, data) in
    if event == .open {
        ...
    } else if event == .error {
        let error = data as? HCaptchaError
        print("onEvent error: \(String(describing: error))")
        ...
    }
}

对于RxSwift

let hcaptcha = try? HCaptcha(...)
...
hcaptcha.rx.events()
    .subscribe { [weak self] rxevent in
        let event = rxevent.element?.0

        if event == .open {
            ...
        }
    }
    ...

SwiftUI示例

HCaptcha最初设计用于与UIKit一起使用。但是您也可以轻松地与SwiftUI一起使用。查看SwiftUI示例

Objective-C 示例

HCaptcha 可从 Objective-C 代码中调用。查看 示例项目

编译大小：包含在应用中对大小的影响

HCaptcha pod 大小：截至 2022 年 5 月 16 日为 90 KB。您可以通过搜索“pod size”字符串在 CI 日志中查看最新数字。

许可证

HCaptcha 在 MIT 许可下提供。有关更多信息，请参阅 LICENSE 文件。

故障排除

问：我遇到了“无法加载嵌入式 HTML”的异常。这意味着什么？答：很可能是您没有将资产包含在构建中。请再次检查，并查看示例应用以获取更多详细信息。

问：在升级 SDK 后，我遇到了“xcconfig：无法打开文件”。（或更改 SDK 并运行 Example 应用。）答：在您的应用或 Example 应用目录中，运行 pod deintegrate && pod install 以刷新路径。

灵感

最初从 fjcaetano 的 ReCaptcha IOS SDK 分支，许可协议为 MIT。