All Products
Search

This Product

    Web Application Firewall:Integrate the SDK for web applications

    Document Center

    Web Application Firewall:Integrate the SDK for web applications

    Last Updated:Apr 22, 2026

    To configure scenario-specific anti-crawler rules, you must integrate the Anti-Bot SDK into your application. This topic explains how to integrate the SDK into web applications.

    Components

    The Anti-Bot SDK integration includes a web collector and an asynchronous API response component.

    Web collector

    The web collector integrates client browser or container features into the anti-bot system. This helps identify attack methods that are undetectable by analyzing only network-level characteristics, improving protection.

    The web collector gathers, obfuscates, and encrypts these features, then plants a cookie on the root domain and reports the data through requests. This process minimally impacts performance.

    The web collector gathers three main types of information:

    • Browser or container environment information: Includes common details like browser type and version, screen resolution, time zone, and timestamp.

    • Specific defense probes: These probes are designed to detect common browser-level bot scripts, drivers, and automated containers.

    • User behavior: Mouse, keyboard, and touch events on the page.

      Note

      For privacy reasons, only the timing of keystrokes is collected, not the specific keys that are pressed.

    Asynchronous API response component

    The asynchronous API response component lets your web application handle challenges that the anti-bot system sends to an API. These challenges currently include JavaScript validation and CAPTCHA challenges. When WAF issues a challenge response to an API, this component detects and responds to it.

    The asynchronous API response component is purely functional. It does not provide any security features and does not collect or report any data.

    The asynchronous API response component works as follows:

    1. The component globally rewrites common API request objects on the page, such as xmlHttpRequest (XHR), Fetch, and Form. It wraps these objects with an additional layer of code without altering their original properties.

    2. After hooking is complete, the component intercepts the response to a request before the page's own JavaScript code can process it. It checks whether the response is a challenge action returned by WAF, such as JavaScript validation or a CAPTCHA challenge.

    3. If the response is from the origin server, the component takes no action and passes it to your website's JavaScript code. However, if the response is from WAF, the component parses the algorithmic content in the response, performs the required JavaScript computation, and resends the request with a new validation signature. WAF verifies the signature and allows the request to pass through to the origin server.

    Compatibility

    • Environment compatibility: The SDK is compatible with browsers that use the Internet Explorer 8 rendering engine or later, and with various client containers.

    • Cookie dependency: Client requests must be able to carry cookies. The component's functionality is impaired if the container or the request does not support cookies.

    • Hook compatibility: In certain business scenarios, custom hooks on native XHR, Form, or Fetch objects may conflict with the asynchronous API response component.

    Integration methods

    Alibaba Cloud provides a JavaScript-based SDK to enhance protection for web browsers and resolve potential compatibility issues. Two integration methods are available: automatic and manual.

    • Automatic integration: Enable integration with a single click. You do not need to modify your business code.

    • Manual integration: Automatic injection of the Web SDK is not supported for protected objects that are added to WAF using Application Load Balancer (ALB), Microservices Engine (MSE), API Gateway (APIG), Function Compute (FC), or Serverless App Engine (SAE). You must manually integrate the Web SDK.

    Automatic integration

    In the upper-right corner of the Web Protection page, click WebSDK Integrations. Then, enable automatic web SDK injection for the protected object.image

    Note

    • After you create a web protection template and enable automatic web SDK integration, the ssxmod_itna, ssxmod_itna2, and ssxmod_itna3 cookies are inserted into the HTTP header to collect client browser fingerprint information. This information includes the host field of the HTTP header, browser height and width, and other details.

    • After you enable automatic integration, the system automatically injects the SDK into the HTML pages of the corresponding protected objects. The SDK is used to collect browser environment information, probe data for illicit tools, and operation behavior logs. It does not collect sensitive personal information.

    Manual integration

    In the upper-right corner of the Web Protection page, click WebSDK Integrations, and then click Obtain SDK. Place the obtained <script> tag before all other <script> tags on your page to ensure it loads first.