tencent cloud

All product documents
Captcha
DocumentationCaptchaIntegration GuideClient IntegrationIntegration of IOS Client SDK
Integration of IOS Client SDK
Download PDF
Last updated: 2025-03-25 11:16:49
Integration of IOS Client SDK
Last updated: 2025-03-25 11:16:49
Download PDF

Service Process Diagram



Privacy Settings

Privacy Policy Link: Privacy Policy | Captcha.

Before adapting, integrating, or loading this SDK product into your product, application, or service, you should carefully read and agree to the related service agreement, these rules, and/or the third-party developer compliance guide (or similar legal documents) that we have published, and conduct a compliance self-check on the collection and use of personal information by the product that adapts, integrates, or loads this SDK product.
If you do not agree with any part of the privacy agreement, you should immediately stop accessing and using the SDK and/or related services. You should use this SDK product and process end users' personal information only after obtaining their consent. Before obtaining end users' consent, you should not enable or initialize this SDK.

iOS SDK Integration

 Integrate the SDK into your project.
Drag the TencentCaptcha directory from the SDK package into your project.
In Xcode, click your project and target, then open the "Build Settings" tab.
Locate "Library Search Paths", expand it, and add the Captcha directory if it is not automatically added.
Locate "Header Search Paths", expand it, and add the Captcha directory if it is not automatically added.
Ensure TencentCaptcha.a is linked with your project (Link Binary with Libraries).
Configuration Parameters
// Set the Captcha App ID before any logic that calls Tencent Captcha service
TencentCaptcha.setup { config in
// Replace __YOUR_CAPTCHA_APP_ID__ with your Captcha App ID
   config.appID = __YOUR_CAPTCHA_APP_ID__ 
}
Set up WebView
The instance of WKWebView needs to be initialized by you. Due to some system limitations, the SDK cannot currently receive WKWebView generated from StoryBoard.
override func viewDidLoad() {
super.viewDidLoad()
// Do any additional setup after loading the view.
let contentController = WKUserContentController()
let config = WKWebViewConfiguration()
   config.userContentController = contentController
   webView = WKWebView(frame: self.view.bounds, configuration: config)
   webView.navigationDelegate = self
   webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
self.view.addSubview(webView)
}
Guide users to agree to privacy policy
Important: Do not use this SDK until the user agrees to the privacy policy. Please configure the SDK as follows after the user agrees to the privacy policy:
TencentCaptcha.userDidAcceptPrivacyPolicy = true
Obtain Captcha characters
TencentCaptcha.shared().requestCaptcha(withWebView: self.webView, options:options) { error, result in
if let error = error {
// If an error occurs, error is non-null
}
else {
// result is the return value
}
}

Set Parameters for the Captcha Interface

The `options` parameter passed when calling `TencentCaptcha.requestCaptcha()` can be configured to some additional parameters. Please refer to the definition of `TencentCaptchaOptions` for details.
Additional parameters can also be configured using `TencentCaptchaOptions.setExtractParameter()`. For example:
let options = TencentCaptchaOptions()
        options.loadingEnabled = TencentCaptchaOptionsSwitchOn
        options.setExtractParameter(true, forName: "enableAutoCheck")

TencentCaptcha.shared().requestCaptcha(withWebView: self.webView, options:options) { error, result in
    // ...
}

Configuration Name
Value Type
Description
enableAutoCheck
Bool
Once enabled, auto-completion of verify selection for secure requests can be performed with no action required by the user.
true: Enable
false: Disable (default)

Class Declaration

TencentCaptchaOptions

Captcha Request Parameters
See `-requestCaptchaWithWebView:options:withCompletionHandler:`TencentCaptcha
/// Night mode option
typedef enum : NSUInteger {
    /// Default
    TencentCaptchaOptionsDarkModeDefault,
    /// Turn on with the system
    TencentCaptchaOptionsDarkModeTrue,
    /// Always off
    TencentCaptchaOptionsDarkModeFalse,
    /// Force open
    TencentCaptchaOptionsDarkModeForce,
} TencentCaptchaOptionsDarkMode;

typedef enum : NSUInteger {
    TencentCaptchaOptionsSwitchDefault,
    TencentCaptchaOptionsSwitchOn,
    TencentCaptchaOptionsSwitchOff,
} TencentCaptchaOptionsSwitch;

/// Captcha Request Parameters
@interface TencentCaptchaOptions : NSObject

/// Custom pass-through parameters. The business can use this field to transmit a small amount of data. The content of this field will be entered into the object of the callback.
@property (nonatomic, strong, nullable) NSString *bizState;

/// Night mode
@property (nonatomic, assign) TencentCaptchaOptionsDarkMode darkModeEnabled;

/// Help button switch
@property (nonatomic, assign) TencentCaptchaOptionsSwitch needsFeedback;

/// Custom URLs of the help button
/// @discussion If `customFeedbackURL` is not empty, the `needsFeedback` option is unavailable, the help button is always displayed, and it navigates to this URL when clicked.
@property (nonatomic, strong, nullable) NSString *customFeedbackURL;

/// Specify the language of the Captcha prompt copy. The priority is higher than the console configuration.
@property (nonatomic, strong, nullable) NSString *userLanguage;

/// Aging adaptation mode
@property (nonatomic, assign) TencentCaptchaOptionsSwitch agedEnabled;

/// Define the display method of the Captcha
/// @discussion popup (default): Display the Captcha in a centered popup floating layer form. embed: Display the Captcha by embedding it into the specified container element.
@property (nonatomic, strong, nullable) NSString *type;

/// Whether to show a loading box during the Captcha loading process
@property (nonatomic, assign) TencentCaptchaOptionsSwitch loadingEnabled;

/// CaptchaAppId encrypted validation string
/// @discussion See https://www.tencentcloud.com/zh/document/product/1159/49680?lang=zh&pg=#captchaAppid
@property (nonatomic, copy, nullable) NSString *encryptedAppID;


/// Set additional parameters
/// @param value Parameter value
/// @param name Keyword name of the parameter
/// @discussion When the parameter corresponding to name does not exist, a new value will be inserted. If it exists, the new value will overwrite the old one; when value is nil, this parameter will be deleted.
- (void)setExtractParameter:(nullable id)value forName:(nonnull NSString *)name;

/// Additional parameters currently set
@property (nonatomic, strong, readonly, nonnull) NSDictionary<NSString *, id> *extractParameters;

/// Parameter and intermediate process callback
/// @discussion When you need to receive intermediate parameters, set up this callback.
@property (nonatomic, copy, nullable) void(^optionsCallback)(NSString *_Nonnull functionName, NSDictionary<NSString *, id> *_Nonnull data);

@end

TencentCaptchaOptionsDarkMode
Night mode options
/// Night mode options
typedef enum : NSUInteger {
/// Default
   TencentCaptchaOptionsDarkModeDefault,
/// Enabled with system
   TencentCaptchaOptionsDarkModeTrue,
/// Always disabled
   TencentCaptchaOptionsDarkModeFalse,
/// Force enabled
   TencentCaptchaOptionsDarkModeForce,
} TencentCaptchaOptionsDarkMode;
TencentCaptchaOptionsSwitch
Switch Option
/// Switch Option
typedef enum : NSUInteger {
    TencentCaptchaOptionsSwitchDefault,
    TencentCaptchaOptionsSwitchOn,
    TencentCaptchaOptionsSwitchOff,
} TencentCaptchaOptionsSwitch;
TencentCaptchaConfiguration
Captcha Service Configuration
See: `+setupWithConfigurationHandler:`TencentCaptcha
/// Captcha service configuration
/// @discussion
/// Used to configure the service in `+[TencentCaptcha TencentCaptcha:]`
@interface TencentCaptchaConfiguration : NSObject
- (nonnull instancetype)init NS_UNAVAILABLE;
@property (nonnull, nonatomic, copy) NSString *appID;
/// Tars server address
/// @discussion If you are unsure of its purpose, do not set it
@property (nullable, nonatomic, copy) NSURL *tarsServerURL;
/// The URL of the Captcha HTML page
/// @discussion If you are unsure of its purpose, do not set it
@property (nullable, nonatomic, copy) NSURL *webPageURL;
/// Whether to allow using cached tokens to speed up the request process
/// @discussion The default is YES, and the caching strategy can meet most scenarios. If you are particularly concerned about real-time risks, set it to NO
@property (nonatomic, assign) BOOL usesCacheToken;
@end

TencentCaptcha

/// The implementation class of the Captcha service
@interface TencentCaptcha : NSObject
- (nonnull instancetype)init NS_UNAVAILABLE;
/// The singleton of the Captcha service
+ (nonnull instancetype)sharedService NS_SWIFT_NAME(shared());
/// Configuration service options
/// - Parameter configurationHandler: To modify the configuration, change the properties in the configuration provided in this callback function
- (void)setupWithConfigurationHandler:(nonnull void(^)(TencentCaptchaConfiguration *_Nonnull))configurationHandler NS_SWIFT_NAME(setup(configurationHandler:));
/// Request Captcha
/// - Parameters:
///   - webView: The web view used to display the Captcha
///   - options: Captcha request parameters
///   - completionHandler: Completion callback for verification
///
/// @discussion Due to some system limitations, the SDK cannot currently receive WKWebView generated from StoryBoard.
- (void)requestCaptchaWithWebView:(nonnull WKWebView *)webView options:(nullable TencentCaptchaOptions *)options withCompletionHandler:(nonnull void(^)(NSError *_Nullable error, NSDictionary *_Nullable result))completionHandler NS_SWIFT_NAME(requestCaptcha(withWebView:options:withCompletionHandler:));

/// Set additional parameters
/// @param value Parameter value
/// @param name Keyword name of the parameter
/// @discussion When the parameter corresponding to name does not exist, a new value will be inserted. If it exists, the new value will overwrite the old one; when value is nil, this parameter will be deleted.
- (void)setExtractParameter:(nullable id)value forName:(nonnull NSString *)name;

/// Additional parameters currently set
@property (nonatomic, strong, readonly, nonnull) NSDictionary<NSString *, id> *extractParameters;

@end

Field Description

Field description of error in the completion callback (completionHandler).
When an error occurs, error is non-null and result is null. See Common mistakes.
Field description of result in the completion callback (completionHandler).
When the Captcha completes normally, error is null and result is non-null. Note that user verification failure is considered a normal completion of the Captcha.
Field Name
Value Type
Description
ret
Int
Verification result, 0: Verification successful.
ticket
String
Ticket returned by the Captcha, ticket has a value if and only if ret = 0.
CaptchaAppId
String
Captcha Application ID.
bizState
Any
Custom pass-through parameters.
randstr
String
The random string for this verification, which needs to be passed during subsequent ticket verification.
errorCode
Number
Error code. For details, see Callback function errorCode description.
errorMessage
String
Error message.

Common mistakes

Device Safety Layer Error (Error Domain TSLocalErrorDomain)

Error Code
Description
0
No error
1
Request protocol packaging error
2
Reply protocol unpacking error
3
Empty reply error
31
X1 protocol data compression error
4
Shark protocol shark layer unpacking error
5
Shark protocol shark layer does not contain sashimi
6
Shark protocol sashimi layer unpacking error
7
Shark protocol sashimi layer empty packet error
8
Shark protocol registration GUID error
9
Shark protocol save GUID error
10
Shark protocol unrecognized command word
20
Session expiration
21
Abnormal return of Shark Skin layer
22
Shark Skin layer unpacking error
23
Shark protocol sashimi layer return value is non-zero
11
The record is empty
12
The record content is invalid or some data is missing (error details available in DEBUG mode)
13
GUID not included when sending Shark request (currently only theoretically possible)
14
Record not included when sending Shark/WUP request
15
Current GUID does not correctly correspond to server type
16
Neither error nor server response included when generating reply content (currently only theoretically possible)
17
Client error for HTTP request (status code between 400~499)
18
Server error for HTTP request (status code between 500~599)
19
Received response does not correspond to the request
25
Temporarily unable to request
26
Illegal internal call
27
Request timeout
28
Illegal communication protocol, or incorrect communication protocol selected
29
Request queue too long
30
User/business side cancels the request
24
Internal testing reserved
34
Serialization failure when generating a token.
35
User has not agreed to the privacy policy.
38
Channel number not correctly set


 

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Contact Us
Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon