tencent cloud

Integration
Download PDF
Last updated: 2025-10-24 14:12:47
Integration
Last updated: 2025-10-24 14:12:47
Download PDF

Non-standard integration issues

What issues will occur if the Captcha JS is not dynamically loaded?

1. Integration method: When the Captcha on Web/App clients is integrated, dynamic loading of JavaScript is not used. Instead, alternative methods are employed to skip the loading process.
2. Security risks: If the above methods are used, CAPTCHAs cannot be updated and consequently some legitimate requests rather than malicious requests might be blocked, and errors might be reported in the frontend.
3. Solution: Dynamically introduce the Captcha JS. For more information, please see Web Integration.

What issues will occur if ticket verification is not integrated?

1. Integration method: The client integrates to Captcha, but the server does not.
2. Security risks: If ticket verification is not integrated, the black market can easily forge verification results, which defeats the purpose of human verification via CAPTCHAs.
3. Solution: Integrate the server to ticket verification. For more information, please see Integration to Ticket Verification (Web and App).

Cross-Platform Framework (React-Native, Flutter) Webview Access Issue

Why Frequent Risk Control Interception in Development Testing？

When the Webview component uses built-in HTML content, since there is no clear domain origin, the browser will deem it as null or the file:// protocol. This can cause the risk control system to report such devices as abnormal. When using built-in HTML, it is recommended to set a baseUrl to specify a valid domain origin. Example configuration:
<WebView
  source={{
    html: captchaHtml, // HTML string template
    baseUrl: 'https://ca.turing.captcha.qcloud.com'  // Use Tencent Captcha domain name as baseUrl
  }}
  ....// other necessary configuration
/>

Web and App integration issues

During the test, the prompt "Too many attempts. Try again later." was displayed. How do I resolve this issue?

This is because the Captcha service blocks suspected malicious users. You may have frequently and intensively accessed the Captcha service of the same scenario in the same network environment, resulting in small-scale risk control blocking. Solutions:
Perform the test again after 10-20 minutes.
Change the IP or device and try again.
Log in to the Captcha console, go to the Security Configuration page of the verification, and adjust the malicious request blocking level to Loose.

Android uses the Web frontend HTML5 method for integration. During the debugging process, a blank background pops up first and then the CAPTCHA page. How do I change that?

During the debugging process, normally, the webview is called first to load the webpage and then the CAPTCHA page pops up.
If the blank background pops up first and then the CAPTCHA page, the reasons are as follows:
The time of loading the Captcha JS results in a white screen.
The page has no content, so the loaded webview is displayed. In this case, it is necessary to display the webview after the ready event is triggered.
Therefore, Android needs to load the page without displaying it, wait for the ready callback, and then display the page after being notified to do so. For ready configuration instructions, see Web Integration - Create Captcha Object.
options={ready: function(size){
// Communicate with Android
}}
new TencentCaptcha(appId, callback, options);

What should I do when CAPTCHAs are not completely displayed on the app?

CAPTCHAs are displayed in the center based on the width and height of the container. CAPTCHAs may be truncated if the width of the container is too wide, causing the incomplete display of the CAPTCHAs. In this case, you need to adjust the pop-up window. In addition, random loading of other webviews may also cause truncation.

What should I do if the Captcha domain name is blocked by a carrier?

Note:
After the main Captcha domain name is blocked by a carrier, you can use the method of dynamically requesting JS-SDK to determine and then request our backup domain name.
<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Web Domain Name Switching Demo</title>
</head>

<body>
  <div id="cap_frame"></div>
</body>
<script>
  // Maximum time to load script
  const MAX_SCRIPT_LOAD_TIME = 10000;
  /**
   * load script promise
   * @param {object} config
   */
  function loadScriptPromise(config) {
    return new Promise((resolve, reject) => {
      loadScript(config, (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      });
    });
  }
  /**
   * error callback
   * @param {string} captchaAppid
   */
  function errorCallback(captchaAppid) {
    // error ticket
    const ticket = `trerror_1001_${captchaAppid}_${Math.floor(new Date().getTime() / 1000)}`;
    const result = {
      ret: -1,
      randstr: `@${Math.random().toString(36).substr(2)}`,
      ticket,
      errorCode: 1001,
      errorMessage: 'jsload_error',
    };
    console.log(result);
  }
  /**
   * success  callback
   * @param {object} result
   */
  function globalCallback(result) {
    console.log(result);
  }

  /**
   * dynamic load script
   * @param {object} src timeout
   * @param {function} cb
   */
  function loadScript({ src, timeout = MAX_SCRIPT_LOAD_TIME }, cb) {
    const startTime = Date.now();
    const script = document.createElement('script');
    script.async = true;
    script.src = src;
    let finished = false;
    const cleanup = () => {
      if (script.parentNode) {
        script.parentNode.removeChild(script);
      }
      script.onload = null;
      script.onerror = null;
    };
    const executeCallback = (err, result) => {
      if (finished) return;
      finished = true;
      clearTimeout(timer);
      cleanup();
      cb(err, result);
    };
    var timer = setTimeout(() => {
      executeCallback(new Error('Script load timeout'));
    }, timeout);

    script.onload = () => {
      const cost = Date.now() - startTime;
      executeCallback(null, cost);
    };
    script.onerror = () => {
      executeCallback(new Error('Script load error'));
    };
    document.head.appendChild(script);
  }
  /**
   * use  captcha sdk
   * @param {string} appid
   */
  function useCaptcha(appid) {
    const captcha = new TencentCaptcha(
      document.getElementById('cap_frame'),
      appid,
      globalCallback,
      {},
    );
    captcha.show();
  }
  /**
   * load captcha sdk
   * @param {string} appid
   */
  async function loadCaptchaSDK(appid) {
    const MAX_SCRIPT_LOAD_TIME = 10000;
    const cdnUrls = [
      'https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js',
      'https://www.tycaptcha.com/TJNCaptcha-global.js',
    ];
    for (const [index, src] of cdnUrls.entries()) {
      try {
        console.log(`Trying Domain ${index + 1}: ${src}`);
        await loadScriptPromise({ src, timeout: MAX_SCRIPT_LOAD_TIME });
        console.log(`Domain ${index + 1} Load Success`);
        return useCaptcha(appid);
      } catch (error) {
        console.warn(`Domain ${index + 1} Load Failed:`, error.message);
        if (index === cdnUrls.length - 1) {
          console.error('All Domains Load Failed');
          return errorCallback(appid);
        }
      }
    }
  }
  loadCaptchaSDK('Yours CaptchaAppid').catch(console.error);
</script>
</html>

Server Integration Issues

Verifying What Risk Types Are Included in Return Values of the Captcha Ticket API?

EvilBitmap Field Description

EvilBitmap is a decimal int type value that needs to be converted to a binary value for use. Each binary bit represents a major category of risk control interception policy.
Binary Bit
Major Category of Risk Control Interception Policy
Example
0
Second-level dial proxy IP address exception

EvilBitmap returns 34, which is converted to the binary value 100010. The first and fifth binary bits of it are 1, indicating the corresponding risk control interception policies are IP address short-term aggregation exception + Data parameter exception.
1
IP address short-term aggregation exception (multiple verifications in a short time)
2
CaptchaAppId + IP address short-term aggregation exception (multiple verifications in a short time)
3
CaptchaAppId + IP address + Device short-term aggregation exception (multiple verifications in a short time)
4
Traffic feature exception (for example, TCP protocol stack information exception)
5
Data parameter exception (for example, browser parameter exception)
6
Honeypot exception (Execute the logic that should not be executed.)
7
Behavior clustering exception

DeviceRiskCategory Field Description

Code
Risk Type
Description
101
Comprehensive score risk
-
102
Simulate mouse trace risk
Suspected machine simulating mouse trace (applicable only to browser)
201
Malicious request risk
Suspected use of tools to initiate malicious requests.
301
Emulator risk
Suspected use of emulators
401
Device tampering risk
Suspected tampering of device hardware information.
501
Suspected black market risk
Suspected use of black and gray market devices.
601
Behavior risk
Suspected use of automated operations.
701
Browser risk
Suspected tampering of browsers.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback