All Products
Search
Document Center

Captcha:Integrate with the V3 architecture on iOS

Last Updated:Oct 23, 2025

As hybrid mobile application (Hybrid App) technology matures, you can use the WKWebView component in your app to directly integrate with Alibaba Cloud Captcha 2.0 for mobile HTML5 services. This provides human and machine verification for your app. This topic describes how to integrate Captcha 2.0 into an iOS app using Swift.

Background information

The mobile HTML5 version of Captcha V2.0 provides benefits such as rapid iteration and high compatibility. By integrating the Captcha V2.0 service into your app, you can avoid compatibility issues caused by dependencies or references in native app components. The rapid iteration of the mobile HTML5 Captcha V2.0 also helps your app better respond to highly adversarial scenarios.

Integration overview

Note

If your service architecture is V2, see Integrate with the V2 architecture on iOS.

Integrating Captcha 2.0 for HTML5 applications into an iOS app involves the following steps:

  1. HTML5 service client: Integrate Captcha 2.0 into the HTML5 service client and initiate the verification.

  2. Server for the HTML5 service: Integrate the Captcha 2.0 SDK on the server and call the VerifyIntelligentCaptcha API operation to initiate signature verification for your service.

  3. iOS app: Use the WKWebView component to enable and deploy the service page that requires Captcha 2.0 integration in your app.

Prerequisites

  • The Alibaba Cloud Captcha 2.0 service is activated.

  • A verification scenario is created. The Integration Method is set to Webview+H5 (Supports Apps And WeChat Mini Programs).

  • Use iOS 10.0 or later.

Procedure

Step 1: Integrate Alibaba Cloud Captcha 2.0 into the HTML5 service client

  1. In the HTML5 service client code, integrate the client-side integration code provided by Captcha 2.0. For more information about how to integrate the HTML5 service client, see Integrate with the V3 architecture for web and H5 clients.

    Note

    If your service architecture is V2, see Integrate with the V2 architecture for web and H5 clients.

  2. In the success callback function, add the corresponding JavaScript function. In this function, call the method that is configured in Step 3 and Step 4. This method uses the WkScriptMessageHandler protocol to enable interaction between JavaScript and WKWebView and obtain the signature verification parameters. After you obtain the parameters, you can send service or signature verification requests from the iOS app and process the verification results.

    // success callback function
    function success(captchaVerifyParam) {
      // Call the JavaScript method implemented by the WkScriptMessageHandler protocol to obtain the signature verification parameters.
      window.webkit && window.webkit.messageHandlers.getCaptchaVerifyParam.postMessage(captchaVerifyParam)
    }

Returned data

In the V3 client architecture for Captcha 2.0, the Captcha server performs behavioral verification by validating the user's response and determining if the request is from a machine. The server then returns the Captcha code and other parameters to the client. You can view the returned data using the Network feature of your browser. For more information, see Data returned by the V3 client architecture.

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

Step 2: Integrate Alibaba Cloud Captcha 2.0 on the server for the HTML5 page

On the server for the HTML5 service page, integrate the server-side SDK provided by Captcha 2.0. Then, call the VerifyIntelligentCaptcha API operation to initiate signature verification for your service. For more information, see Server-side integration.

Step 3: Enable and deploy the service page in the iOS app

Swift

  1. In the Controller.swift file of your iOS app project, import the required dependencies.

    import WebKit
  2. In the Controller.swift file of your iOS app project, load the HTML5 service page.

    override func viewDidLoad() {
        super.viewDidLoad()
        view.addSubview(webView)
        let url = URL(string: "http://x.x.x.x/demo/")
        let request = URLRequest(url: url!);
        webView.load(request); // Load the page.
    }
  3. Set the WKWebView object. Use the WKScriptMessageHandler protocol to enable interaction between JavaScript and WKWebView.

    lazy var webView: WKWebView = {
        // Configure adaptive page scaling.
        let javascript = "var meta = document.createElement('meta'); meta.setAttribute('name', 'viewport'); meta.setAttribute('content', 'width=device-width'); document.getElementsByTagName('head')[0].appendChild(meta)";
        let configuration = WKWebViewConfiguration();
        let userScript = WKUserScript(source: javascript, injectionTime: .atDocumentEnd, forMainFrameOnly: true);
        let usercontroller = WKUserContentController();
        usercontroller.addUserScript(userScript);
        configuration.userContentController = usercontroller;
        // Add the method to call JavaScript from the HTML page. You can change the method name as needed.
        configuration.userContentController.add(self, name: "getCaptchaVerifyParam");
        // Configure WKWebView.
        let webView = WKWebView(frame: self.view.frame, configuration: configuration);
        webView.navigationDelegate = self;
        return webView;
    }()
  4. Set the corresponding method for the WKScriptMessageHandler protocol. Use this method to obtain the return value from Captcha 2.0, process it with your service logic, and then return the verification result to a custom API.

    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if(messsage.name == "getCaptchaVerifyParam"){
            // After you obtain the signature verification parameters, you can send service or signature verification requests and process the results.
            print(message.body)
        }
    }

Objective-C

  1. In the ViewController.m file of your iOS app project, import the required dependencies.

    #import "ViewController.h"
    #import <WebKit/WebKit.h>
    
    @interface ViewController ()<WKScriptMessageHandler>
    
    @property(nonatomic,strong)WKWebView *webView;
    
    @end
  2. In the ViewController.m file of your iOS app project, load the HTML5 service page.

    - (void)viewDidLoad {
        [super viewDidLoad];
        
        [self.view addSubview:self.webView];
        self.webView.scrollView.backgroundColor = [UIColor redColor];
        
        [self loadLocalHtmlForJs];
    }
    
    - (void)loadLocalHtmlForJs{
        NSString *path = [[NSBundle mainBundle] pathForResource:@"index" ofType:@"html"];
        NSURLRequest *req = [NSURLRequest requestWithURL:[NSURL fileURLWithPath:path]];
        [self.webView loadRequest:req];
    }
  3. Set the WKWebView object. Use the WKScriptMessageHandler protocol to enable interaction between JavaScript and WKWebView.

    - (WKWebView *)webView{
        if (!_webView) {
            // Configure adaptive page scaling.
            NSString *jscript = @"var meta = document.createElement('meta'); meta.setAttribute('name', 'viewport'); meta.setAttribute('content', 'width=device-width'); document.getElementsByTagName('head')[0].appendChild(meta)";
            WKUserScript *userScript = [[WKUserScript alloc] initWithSource:jscript injectionTime:WKUserScriptInjectionTimeAtDocumentEnd forMainFrameOnly:YES];
            WKUserContentController *userContentController = [[WKUserContentController alloc] init];
            [userContentController addUserScript:userScript];
            // Add the method to call JavaScript from the HTML page. The method name must be the same as the one called in the success callback function of the HTML page.
            [userContentController addScriptMessageHandler:self name:@"getCaptchaVerifyParam"];
            // Configure WKWebView.
            WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc] init];
            configuration.userContentController = userContentController;
            // Display WKWebView.
            WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.frame configuration:configuration];
            webView.backgroundColor = [UIColor blackColor];
            // Enable debug mode (Optional).
            [webView.configuration.preferences setValue:@YES forKey:@"developerExtrasEnabled"];
            webView.inspectable = YES;
    
            _webView = webView;
        }
        return _webView;
    }
  4. Set the corresponding method for the WKScriptMessageHandler protocol. Use this method to obtain the return value from Captcha 2.0, process it with your service logic, and then return the verification result to a custom API.

    - (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message {
        // Obtain the return value from the Captcha service by calling the corresponding method from the HTML page's JavaScript. The method name must be the same as the one added for the JavaScript call.
        if([message.name isEqualToString:@"getCaptchaVerifyParam"]){
            // After you obtain the signature verification parameters, you can send service or signature verification requests and process the results.
            NSLog(@"Signature verification parameters for Captcha: %@", message.body);
            // You can add your service logic here. For example:
            // 1. Send the signature verification parameters to your server for verification.
            // 2. Process subsequent business flows based on the verification result.
            
            // Example: Send the signature verification parameters to the server.
            [self sendCaptchaVerifyParamToServer:message.body];
        }
    }

iOS V3 architecture demo downloads