快速上手

WlzShield Captcha 提供了一套简单易用的 SDK，帮助您在几分钟内完成验证码的接入。

新一代行为验证安全组件。

安全、有趣、易集成的 HTML5 验证码解决方案。

1. 引入资源

请确保在页面中的head引入了组件库文件。

<script src="https://captcha.wangluozhe.com/static/js/vendors.min.js"></script>
<script src="https://captcha.wangluozhe.com/static/js/wlzshield.min.js"></script>

2. 准备容器

在您的页面中准备一个空的 div 容器，用于挂载验证码组件。请务必指定一个唯一的 id。

<div id="captcha-box"></div>

3. 初始化组件

根据您的业务场景选择合适的组件进行初始化。

刮刮乐 (Scratch)

// 适用于营销活动、高安全等级场景
new WlzShield.ScratchCaptcha({
    containerId: '#captcha-box',
    onSuccess: function(data) {
        console.log('验证通过，凭证:', data);
        // TODO: 将 data 提交给您的业务接口
    },
});

复选框 (Checkbox)

// 适用于登录、注册等流畅体验场景
new WlzShield.CheckboxCaptcha({
    containerId: '#captcha-box',
    onSuccess: function(data) {
        console.log('验证通过，凭证:', data);
        // TODO: 将 data 提交给您的业务接口
    },
});

4. 后端交互协议 (重要)

当组件验证通过时，SDK 会自动向您配置的challengeUrl 发送 POST 请求，你的后端将前端传来的数据发送给https://captcha.wangluozhe.com/api/challenge。

前端发送的数据 (Payload)

SDK 发送的 JSON 数据结构如下：

{
  "timestamp": 1735299000000,   // 验证码初始化的时间戳
  "wlzData": "...",             // 环境指纹与行为加密数据
  "type": "checkbox",           // 类型："checkbox" 或 "scratch"
  
  // --- 仅刮刮乐模式包含以下字段 ---
  "totalWinners": 5,            // 本次生成的总中奖数
  "totalPrizeValue": 100,       // 本次生成的总奖金数值
  "hitAreas": [...]             // 用户点击轨迹与热区数据
}

后端返回的数据 (Response)

您的后端接口必须返回以下格式的 JSON，组件才能正确处理状态：

✅ 验证成功时返回：

{
  "status": true,
  "msg": "验证成功"
}

❌ 验证失败时返回：

{
  "status": false,
  "msg": "验证失败"
}