ArcCaptcha 快速开始
前端 SDK
引入 SDK
初始化
实例化 CaptchaSDK 时传入的配置项。除 captchaId（标记 *）必填外，其余均为可选项，按需传入即可。
| 参数 | 类型 | 说明 |
|---|---|---|
| captchaId | string * | 必填。在控制台创建应用时获取的 Captcha ID，用于标识你的租户和加载对应的风控策略。 |
| lang | string | 弹层与错误提示的语言：'auto'（按浏览器 navigator.language 推断，默认）或显式指定。支持：'zh-CN'（简体中文）、'zh-TW'（繁体中文，台港澳自动走此）、'en'（英文，新加坡自动走此）、'ja'（日语）、'ko'（韩语）、'id'（印尼语）、'th'（泰语）、'my'（缅甸语）、'vi'（越南语）、'km'（高棉语）、'ms'（马来语）、'pt-PT'（欧陆葡语，葡萄牙/安哥拉/莫桑比克自动走此）、'pt-BR'（巴西葡语）、'fil'（菲律宾语）。未匹配的语言回退到英文。 |
| target | string | Element | 内嵌 checkbox 模式的容器，传入 CSS 选择器或 DOM 元素；不传则使用默认弹窗模式。内嵌模式下 verify() 会在容器内渲染「我不是机器人」复选框。 |
| placement | string | 'top'（参考元素上方） |
| anchor | string | Element | 锚点元素（CSS 选择器或 DOM 元素），仅在弹窗模式下作为 placement 参考，通常设为「提交」按钮。checkbox 模式（设置了 target）下该参数会被忽略，弹窗始终以 target 容器为参考。 |
| theme | string | object | 主题配置：传字符串 'light' / 'dark' 使用预设，或传对象做细粒度自定义。详见下方「主题定制」章节。 |
| brand | object | 企业版品牌定制（logo / 文案 / 链接），仅对开通企业版的租户生效；非企业版传入会被忽略。 |
弹窗位置 (placement)
placement 决定验证弹窗相对参考元素的出现位置。参考元素优先取 target（checkbox 模式的容器），其次 anchor；都没有时回退为视口中心。两种模式（弹窗 / checkbox）下均生效。
| 取值 | 说明 |
|---|---|
| 'auto' (default) | 自动判断：比较参考元素上下两侧的剩余空间，选较大一侧弹出（同 top / bottom 锚定方式）。推荐默认值。 |
| 'top' | 紧贴参考元素上方，水平与参考元素中心对齐，带向下的小三角箭头。 |
| 'bottom' | 紧贴参考元素下方，水平与参考元素中心对齐，带向上的小三角箭头。 |
| 'left' | 紧贴参考元素左侧，垂直与参考元素中心对齐，带向右的小三角箭头。 |
| 'right' | 紧贴参考元素右侧，垂直与参考元素中心对齐，带向左的小三角箭头。 |
| 'center' | 弹窗几何中心对齐参考元素的几何中心（弹窗叠在参考元素上方）。参考元素缺失时退化为 windowCenter。 |
| 'windowCenter' | 弹窗居中于浏览器视口，不依赖参考元素。 |
主题定制
支持两种传法：字符串预设（'light' / 'dark'）快速切换；或对象形式按需覆盖颜色，未指定的字段沿用 preset 基底。所有颜色均接受 6 位十六进制字符串，SDK 会自动生成半透明变体用于渐变和 hover 态。
| 参数 | 类型 | 说明 |
|---|---|---|
| preset | 'light' | 'dark' | 基底预设，作为其余字段的默认值。未指定时使用 'light'。 |
| primary | string | 主要色：高亮边框、加载动画、滑块轨道填充、主按钮背景。默认 '#4facfe'。 |
| secondary | string | 次要色：与 primary 组成渐变的尾色。默认 '#00f2fe'。 |
| success | string | 成功态颜色：验证通过时的对勾和成功背景。默认 '#43e97b'。 |
| error | string | 失败态颜色：错误提示、失败图标。默认 '#f5576c'。 |
| background | string | 弹层背景色。light 预设 '#fff'，dark 预设 '#1e1e2e'。 |
| border | string | 弹层边框色。light 预设 '#d9d9d9'，dark 预设 '#444'。 |
| text | string | 主要文字颜色。light 预设 '#555'，dark 预设 '#ccc'。 |
| hover | string | hover 背景色，用于按钮和交互元素的悬停反馈。light 预设 '#f7f7f7'，dark 预设 '#2a2a3e'。 |
| btnBg | string | 滑块拖拽按钮主色（单一基色，自动派生渐变、阴影、图标对比色）。light 预设 '#ffffff'，dark 预设 '#3a3a4e'。 |
| btnIcon | string | （可选）覆盖按钮内图标颜色。不传时按 btnBg 亮度自动选黑/白，确保对比度。 |
触发验证
| 参数 | 类型 | 说明 |
|---|---|---|
| businessType | string | 业务类型，如 login、sms、comment |
| businessId | string | 业务 ID，如用户名、手机号（前端 SDK 会自动 SHA-256 哈希） |
返回值：
| 参数 | 类型 | 说明 |
|---|---|---|
| seccode | string | 验证凭证，发送给业务后端核销 |
前端集成示例
后端核销
用户完成验证后，前端获得 seccode，业务后端调用此接口核销确认。
请求头
| Header | 说明 |
|---|---|
| X-Captcha-Id | 应用的 Captcha ID |
| X-Timestamp | 当前 Unix 时间戳（秒） |
| X-Signature | HMAC-SHA256(appSecret, captchaId:timestamp:sha256Hex(body)) |
请求体
| 参数 | 类型 | 说明 |
|---|---|---|
| seccode | string | 前端验证通过后获得的凭证 |
| business_type | string | 业务类型，需与前端传入一致 |
| business_id | string | 业务 ID 原文（服务端会 SHA-256 后与 seccode 内的哈希比对） |
响应
签名算法
使用 App Secret 对 captchaId、时间戳、请求体 SHA-256 hash 三者拼接串进行 HMAC-SHA256 签名，时间戳误差不超过 300 秒。签名覆盖请求体，防止攻击者用同一签名重放不同 body。
后端完整示例
下面是一个完整的登录接口实现，演示如何在业务请求中核销前端提交的 seccode，并根据核销结果决定是否继续业务逻辑。
响应说明
核销接口返回 JSON，业务端必须检查 valid 字段：只有为 true 时才算验证通过，否则应直接拒绝本次业务请求。
| 参数 | 类型 | 说明 |
|---|---|---|
| valid | boolean | 是否通过。true 表示 seccode 核销成功，但业务后端仍需检查 bypass 字段区分真实通过与静默放行；false 表示核销失败，必须拒绝本次请求。 |
| reason | string | 核销失败时的原因描述（例如：seccode 无效、已过期、业务上下文不匹配等），valid=true 时为 null。 |
| bypass | boolean | 是否为系统静默放行。true 表示 seccode 并非真实人机校验通过，仅因系统兜底（如套餐配额耗尽）放行。敏感操作（登录、支付、改密）应拒绝此类 seccode。 |
| bypass_reason | string | bypass 原因的机器可读代码，bypass=false 时为 null。当前取值：quota_exceeded。 |
| message | string | 人类可读提示，通常在 bypass=true 时用于运营告警或前端展示，正常路径为 null。 |
验证流程
业务策略配置
你可以为每一个业务场景（比如登录、注册、发短信、发评论）单独设置一套风控规则。前端在调用验证时声明自己属于哪种业务类型，系统就会自动应用对应的配置；没有显式声明的业务类型会沿用应用级默认策略。留空的字段表示不启用该项规则。
操作频次
从整体流量角度判断业务是否异常。在同一个时间窗口内，对这个业务类型触发的所有请求做计数，不区分用户和设备。达到设定的阈值后，后续请求会进入更严格的验证模式，再高就会被直接拦截。
- 时间窗口
- 频次统计的滚动时间范围。所有基于频次的判断都用这个窗口。建议：登录/注册这类低频操作用 1 小时以上，评论/签到等高频操作用 10 分钟左右。
- 可疑阈值（次）
- 窗口内累计请求数一旦越过此值，说明流量明显高于平时，系统会强制弹出「点选文字」这种更难的人机验证，挡掉脚本刷量。
- 封锁阈值（次）
- 窗口内请求数达到这个级别通常意味着正在被刷，系统会直接拦截，不再给出通过的可能，直到窗口过去。
风险模型
在上面「看流量整体」的基础上，进一步从「账号集中度」角度识别风险。适用于注册、绑定手机号等「一个真人原则上不会重复做」的场景。
- 验证码样式
- 决定该业务展示哪种验证方式：选「风险自适应」会根据检测到的风险高低自动在滑块 / 点选之间切换；选「始终滑块」或「始终点选」则固定用一种样式，便于统一 UI。
- 统计窗口（秒）
- 专门服务于下面两个阈值的统计时间范围。留空就复用上面「操作频次」里的时间窗口，一般不需要单独设。
- 同源通过可疑阈值
- 在同一个出口 IP 或同一台浏览器下，同一业务的通过次数越过此值时，系统会认为「一个人在不同账号之间来回切换」，后续这类请求会被当作可疑流量处理，触发更严格的验证。
- 同源通过危险阈值
- 危险级阈值。超过这个值通常意味着有人在用脚本批量注册或刷账号，系统会把这类请求视为正在攻击，直接拦截。
信任策略
信任策略决定「老用户能不能不用做验证码直接过」。满足信任条件的设备，在同一业务类型、同一业务对象上可以静默通过，用户完全感知不到弹窗。不配置任何策略时，该业务永远不会出现静默通过，最高也只会给到最简单的滑块。
常用设备
适合登录、短信等重复使用的入口
适合重复使用的场景。系统会统计这台设备在过去一段时间里有多少个「不同的自然日」成功通过过，当跨天次数足够多时就认为它是自己人，后续同账号同业务直接放行。
- 统计窗口
- 回看多久内的历史记录。默认一个月：例如把它设为 30 天，系统只看最近一个月里的活跃情况，更早的记录不计入。
- 最少天数
- 被信任前至少要在多少个「不同的日历天」出现过成功验证。建议 3 到 7 天，低于 3 天太容易伪造，高于 7 天会让新用户等太久。
- 可疑阈值业务数量
- 一个设备如果在很多不同业务上都被信任了（例如同时是评论、点赞、签到的老用户），反而值得警惕。达到这个数量时系统会降低它的信任级别，强制做一次验证码兜底。
- 封锁阈值业务数量
- 上一项的加强版：如果被信任的业务数量进一步超过此值，基本可以判定为共享设备或脚本池，这类请求会被直接拦截。
稳定设备
适合评论、下载等低频或偶发操作
不看跨天次数，只看两个条件：这台设备「来得够早」并且「最近动得不多」。一旦用户活跃度回升，下一次请求就会重新要求做验证码。
- 最小设备龄（天）
- 设备第一次出现到现在必须经过多少天才有资格被信任。太短的值容易被新注册的自动化流量绕过，建议至少一周。
- 最大频次
- 在下面那个频率窗口里，该设备的成功通过次数不能超过这个数。超出就说明它不再是「偶尔用一次」，需要重新做验证。
- 频次窗口（秒）
- 配合上一项使用的时间窗口。例如设为 1 天，就是「每天最多允许多少次静默通过」。
- 可疑阈值业务数量
- 一个设备如果在很多不同业务上都被信任了（例如同时是评论、点赞、签到的老用户），反而值得警惕。达到这个数量时系统会降低它的信任级别，强制做一次验证码兜底。
- 封锁阈值业务数量
- 上一项的加强版：如果被信任的业务数量进一步超过此值，基本可以判定为共享设备或脚本池，这类请求会被直接拦截。
品牌定制
每个验证码弹窗的底部都会展示一条品牌条，默认是「Protected by ArcCaptcha」。如果你希望换成自己的 logo 和文案，或者完全去掉品牌条，升级到企业版即可。
| 套餐 | 默认 ArcCaptcha 品牌 | 替换为自有品牌 | 完全隐藏品牌条 |
|---|---|---|---|
| 免费版 | ✓ | — | — |
| 高级版 | ✓ | — | — |
| 企业版 | ✓ | ✓ | ✓ |
如何配置（企业版）
在初始化 SDK 的地方多传一个 brand 参数即可，不需要登录控制台、也不需要部署额外的后端逻辑。下方是一段完整示例：
可配置字段
logoUrl— 你自己的 logo 图片 URL（支持 https 外链、站内相对路径，或内联 data URI）。text— 品牌文案，最多 40 字，例如「Secured by 你的公司」。link— 用户点击品牌文字后跳转的链接，必须是 https 完整 URL。hideDefault— 设为 true 时不显示任何品牌内容，弹窗底部完全空白。