Add hCaptcha to your project. This library automatically handles hCaptcha's events and returns a validation token, presenting the challenge via a modal if needed.
To secure your application, you need to send the token received here to your backend for server-side validation via the api.hcaptcha.com/siteverify
endpoint.
HCaptcha is available through CocoaPods and packaged for Carthage and SPM (Swift Package Manager).
To install it, simply add the following line to your dependencies file:
pod "HCaptcha"
# or
pod "HCaptcha/RxSwift"
github "hCaptcha/HCaptcha-ios-sdk"
Carthage will create two different frameworks named HCaptcha
and HCaptcha_RxSwift
, the latter containing the RxSwift extension for the HCaptcha framework.
Known issues:
- Carthage doesn't support prebuilt zips for
xcframework
so use--no-use-binaries
- Carthage/Carthage#3130 - Carthage has a
RxSwift
build issue, also avoidable via--no-use-binaries
- Carthage/Carthage#3243
Standard SPM formula: uses Package.swift
Platform | Requirements |
---|---|
iOS | âś… >= 12.0 |
WatchOS | ✖️ |
hCaptcha sitekeys can be specified as Info.plist keys or can be passed as parameters when instantiating HCaptcha()
.
For the Info.plist configuration, add HCaptchaKey
(sitekey) and HCaptchaDomain
(with a protocol, i.e. https://) to your Info.plist.
HCaptchaKey
is your hCaptcha sitekey.HCaptchaDomain
should be a string likehttps://www.your.com
With these values set, run:
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())
}
}
Note: in case you need to show hCaptcha above UIVisualEffectView
make sure to pass visualEffectView.contentView
instead visualEffectView
. Per Apple's documentation:
After you add the visual effect view to the view hierarchy, add any subviews to the contentView property of the visual effect view. Do not add subviews directly to the visual effect view itself.
More details here.
If you prefer to keep the information out of the Info.plist, you can instead use:
let hcaptcha = try? HCaptcha(
apiKey: "YOUR_HCAPTCHA_KEY",
baseURL: URL(string: "YOUR_HCAPTCHA_DOMAIN")!
)
...
Notes:
- in most cases
baseURL
can behttp://localhost
. This value is mainly used for your convenience in analytics. baseURL
should matchHCaptchaDomain
if specified; it controls the URI used to initialize the hCaptcha session. Example:https://www.your.com
You can also install the reactive subpod and use it with RxSwift:
hcaptcha.rx.validate(on: view)
.subscribe(onNext: { (token: String) in
// Do something
})
Note: caller code is responsible for hiding the WebView
after challenge processing. This is illustrated in the Example app, and can be achieved with:
-
Regular Swift API:
... var captchaWebView: WKWebView? ... hcaptcha?.configureWebView { [weak self] webview in self?.captchaWebView = webview } ... hcaptcha.validate(on: view) { result in ... captchaWebView?.removeFromSuperview() }
-
RxSwift
API (check the example for more details):... 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)
Since this SDK uses local resources, you may want to set a host override for better tracking and enforcement of siteverify parameters.
You can achieve this by passing the extra param host
:
let hcaptcha = try? HCaptcha(
...
host: "your-domain.com",
...
)
...
Note: this should be the bare host, i.e. not including a protocol prefix like https://.
The SDK supports three built-in themes: light
, dark
, and contrast
let hcaptcha = try? HCaptcha(
...
theme: "dark", // "light" or "contrast"
...
)
...
For Enterprise sitekeys we also support custom themes via the customTheme
parameter, described below.
If you are an Enterprise user with first-party hosting access, you can use your own endpoint (i.e. verify.your.com).
You can then enable it in your code:
let hcaptcha = try? HCaptcha(
...
endpoint: URL("https://custom.endpoint")!,
...
)
...
Enterprise params like:
rqdata
(string)reportapi
(string)assethost
(string)imghost
(string)sentry
(bool)customTheme
(string representation of JS Object or JSON; see Enterprise docs)
Can be passed via HCaptcha(...)
Please see the hCaptcha Enterprise documentation for more details.
This iOS SDK assumes by default that you want an "invisible" checkbox, i.e. that triggering the hCaptcha flow from within your app should either return a token or show the user a challenge directly.
If you instead want the classic "normal" or "compact" checkbox behavior of showing a checkbox to tick and then either closing or showing a challenge, you can pass size
to the HCaptcha initializer.
let hcaptcha = try? HCaptcha(size: .compact)
And you will now get the desired behavior.
The orientation
argument can be set either .portrait
or .landscape
orientation to adjust challenge modal behavior.
let hcaptcha = try? HCaptcha(orientation: .landscape)
By default, orientation is portrait and does not reflow.
However, if you have an app used exclusively in landscape mode (e.g. a game) then you can also switch the challenge UI to match this design choice.
This SDK allows you to receive interaction events, for your analytics via the onEvent
method. At the moment the SDK supports:
open
fires when hCaptcha is opened and a challenge is visible to an app userexpired
fires when the passcode response expires and the user must re-verifychallengeExpired
fires when the user display of a challenge times out with no answerclose
fires when the user dismisses a challenge.error
fires when an internal error happens during challenge verification, for example a network error. Details about the error will be provided by thedata
param, as in the example below. Note: This event is not intended for error handling, but only for analytics purposes. For error handling please see thevalidate
API call docs.
You can implement this with the code below:
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))")
...
}
}
For RxSwift
:
let hcaptcha = try? HCaptcha(...)
...
hcaptcha.rx.events()
.subscribe { [weak self] rxevent in
let event = rxevent.element?.0
if event == .open {
...
}
}
...
By default the SDK will automatically fetch a new token upon expiry once you have requested a token via validate
. This behavior can be adjusted by passing resetOnError: false
to the validate
call:
hcaptcha.validate(on: view, resetOnError: false) { result in
...
}
If you are customizing display beyond the defaults and need to resize or change the hCaptcha layout, for example after a visual challenge appears, you can use the following approach to trigger a redraw of the view:
let hcaptcha = try? HCaptcha(...)
var visualChallengeShown = false
...
hcaptcha?.configureWebView { [weak self] webview in
webview.tag = "hCaptchaViewTag"
if visualChallengeShown {
let padding = 10
webview.frame = CGRect(
x: padding,
y: padding,
width: view.frame.size.width - 2 * padding,
height: targetHeight - 2 * padding
)
} else {
webview.frame = self?.view.bounds ?? CGRect.zero
}
}
...
hcaptcha.onEvent { (event, data) in
if event == .open {
visualChallengeShown = true
hcaptcha.redrawView()
} else if event == .error {
let error = data as? HCaptchaError
print("onEvent error: \(String(describing: error))")
...
}
}
...
hcaptcha.validate(on: view, resetOnError: false) { result in
visualChallengeShown = false
}
HCaptcha
was originally designed to be used with UIKit. But you can easily use it with SwiftUI
as well. Check out the SwiftUI Example
HCaptcha
can be used from Objective-C code. Check out the Example Project
HCaptcha Enterprise supports verification with no interaction from the user: Passive Site Keys.
Using the passiveApiKey
option with Passive sitekeys provides performance improvements in SDK token generation time, at the cost of less flexibility if you want to change the sitekey mode in the future without a code update.
Check out the Example for more details.
HCaptcha pod size: 140 KB as of Jan 2024. You can always see the latest number in the CI logs by searching for the "pod size" string.
- WebView crashes on Simulator iOS 14.x (arm64) but not on real devices. More details
HCaptcha is available under the MIT license. See the LICENSE file for more info.
Q. I'm getting a "Could not load embedded HTML" exception. What does this mean?
A. Most likely you have not included an asset in your build. Please double-check assets, and see the example app for more details.
Q. I'm getting "xcconfig: unable to open file" after upgrading the SDK. (Or changing SDK and running Example app.)
A. In your app or the Example app dir, run pod deintegrate && pod install
to refresh paths.
Q: The challenge modal is displayed, but I can't interact with it. How do I fix this?
A: There are several ways this can happen:
-
Your app called
UIApplication.shared.beginIgnoringInteractionEvents()
, which prevents any user interaction, before calling the execute method of the SDK. Make sure to callUIApplication.shared.endIgnoringInteractionEvents()
to re-enable interaction before executing the SDK token request if you use this method. -
You may have unintentionally added a transparent overlay over the SDK's view layer. This can be checked with the view debugger
Originally forked from fjcaetano's ReCaptcha IOS SDK, licensed under MIT.