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:Jul 28, 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

    Log on to the WAF 3.0 console. In the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) of your WAF instance. In the left-side navigation pane, choose Protection Config > Bot Management > Bot Management Template, and go to the Web Protection > WebSDK Integrations tab.

    Alibaba Cloud offers a JavaScript-based Web SDK to improve protection and prevent compatibility issues. The SDK supports two integration methods:

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

    • Manual integration: Suitable for scenarios such as Function Compute (FC) and Serverless App Engine (SAE) that do not support automatic injection. You must manually configure the code.

    Automatic integration

    On the WebSDK Integrations tab, view the protected objects that have been automatically integrated. You can disable integration or adjust the canary release proportion on this page.

    Note

    • After you enable automatic integration, the system automatically injects the SDK into the HTML pages of the protected objects. The SDK is used to collect browser environment information, probe data for malicious tools, and log user behavior (excluding sensitive personal information) to enhance protection.

    • The system also inserts cookies such as ssxmod_itna, ssxmod_itna2, and ssxmod_itna3 into the HTTP response headers to obtain client browser fingerprints. The collected fingerprint information includes data such as the Host field of the HTTP header and the browser window's height and width.

    Manual integration

    On the WebSDK Integrations tab, click Obtain SDK in the description. Place the obtained <script> tag before all other <script> tags on your page to ensure it loads first.