客户端配置指南

应用创建后获取对应客户端 Public Key，在业务前端配置展示即可，无需在后台创建主题或逐个添加 login、register 场景。Server Key 只在业务后端使用。

配置优先级

客户端明确传入的参数 → SDK 默认值。服务端 /config 返回的风险规则仍然有效，但 language、product 不再覆盖 SDK 的前端展示参数。Web 自定义 loadConfig() 本身属于前端代码，其展示值可作为默认值，显式顶层参数优先。

scene 是业务动作标识；业务后端核验时使用该接口预期的场景。challengeMode 是题型偏好，服务端可以拒绝或升级；前端必须按返回的 challenge_type 展示实际挑战。

升级时：原先依赖后台 product=invisible 或固定语言的业务，应在初始化参数中明确填写对应 product / language。默认 popup 不会自动启动验证，需点击 SDK 触发器或调用 Web 的 open()。

公开参数

支持语言：zh-CN、zh-TW、en、es、pt-BR、fr、de、ja、ko、ru、ar、hi、id、tr、vi、th、it、nl、pl、uk、fa、he、ms、fil。共享 Web 组件提供这些语言；原生自绘界面须自行提供对应文案。没有浏览器语言环境时建议显式传入设备语言。

以下为 Web 专属交互接口：container（挂载点）、bindTrigger（绑定已有按钮）、open()（手动打开）、reset()（重置）、destroy()（销毁）、onSuccess（取得待核验 Proof）、onState（ready/required/verified/error）、onEvent（生命周期事件）、onError（展示错误）。Flutter 通过 Future<Proof?> 返回成功/取消，onEvent 用于观察生命周期；其他原生和小程序的完成/错误通过 async/Promise 返回，界面事件由业务 UI 管理。

Web 的 enabled、offlineBypass 是兼容参数：只影响本地组件和失败展示，不会生成可信凭证。生产保持 enabled=true、offlineBypass=false，请求失败应允许用户重试。不要用这些开关跳过业务后端核验。

TypeScript 低阶请求支持 headers、fetch、signal、beforeRequest、afterResponse 等扩展；仅在需要自定义传输时使用。小程序支持 request 适配器、sessionId、telemetry。这些客户端数据不应被业务后端直接当作放行依据。

Web / H5

const captcha = RozeCaptcha.init({
  container: '#captcha',
  captchaId: '你的 Web Public Key',
  apiBase: 'https://pink.ya.wang/api/captcha',
  scene: 'login', clientType: 'web', clientId: 'web',
  language: 'zh-CN', product: 'bind', bindTrigger: '#login-button',
  appearance: { theme: 'auto', primaryColor: '#167d50', borderRadius: 8 },
  challengeMode: 'smart', hapticFeedback: true,
  requestTimeoutMs: 12000, configRetries: 2,
  onSuccess: proof => submitLoginToYourBackend(proof),
  onError: error => showError(error.message),
  onEvent: event => recordCaptchaEvent(event),
})
// 页面卸载：captcha.destroy()

一个页面可以挂载多个实例，各自主题互不影响；弹窗 Teleport 到 body 后仍保留自己的配置。题图宽高和拼图位置不可由业务 CSS 单独拉伸，应使用 SDK 的响应式布局。

在 onState 的 ready=true 后调用 open()；初始化未完成时应让业务触发按钮保持禁用。题图内容、缺口坐标与旋转中心由服务端挑战决定，不属于前端外观配置。

Flutter Android / iOS

final proof = await PinkCaptcha.verify(context, options: PinkCaptchaOptions(
  publicKey: platformPublicKey,
  apiBase: Uri.parse('https://pink.ya.wang/api/captcha'),
  scene: 'login', language: 'zh-CN', product: 'invisible',
  appearance: PinkCaptchaAppearance(
    theme: 'auto', primaryColor: '#167d50', borderRadius: 8,
  ),
  hapticFeedback: true, configRetries: 1,
  requestTimeout: const Duration(seconds: 12),
  onEvent: (event) => recordCaptchaEvent(event),
));
if (proof != null) await submitToYourBackend(proof.toJson());

Flutter 包内自带交互组件，配置直接生效；不需要业务另写 WebView 页面。product=invisible 避免在已经打开的原生弹窗内再点一次触发按钮。原生标题/错误支持中文和英文，题图内文案使用共享组件语言。

iOS Swift

let options = RozeCaptchaOptions(
    baseURL: URL(string: "https://pink.ya.wang")!,
    publicKey: publicKey, scene: "login", clientId: Bundle.main.bundleIdentifier!,
    language: "zh-CN", product: "popup", hapticFeedback: true,
    appearance: .init(theme: "auto", primaryColor: "#167d50", borderRadius: 8)
)
let client = try RozeCaptchaClient(options: options)
let tokens = options.appearance.viewTokens(darkMode: isSystemDark)
// 原生界面：用 tokens 中的 backgroundColor/textColor/primaryColor/borderRadius 设置自己的视图。
let webOptions = options.webOptions()
// 如已有 WebView 容器：JSONSerialization 编码 webOptions，传给共享 RozeCaptcha.init。

Android Kotlin

val options = RozeCaptchaOptions(
    baseUrl = "https://pink.ya.wang", publicKey = publicKey,
    scene = "login", clientId = context.packageName,
    language = "zh-CN", product = "popup", hapticFeedback = true,
    appearance = RozeCaptchaAppearance("auto", "#167d50", 8),
)
val client = RozeCaptchaClient(options)
val tokens = options.appearance.viewTokens(darkMode = isSystemDark)
// 将 tokens 绑定到自绘界面；或把 options.webOptions() 序列化后交给已有 WebView。

Swift/Kotlin 包提供请求层、配置校验、界面颜色与圆角参数，以及共享 Web SDK 参数映射，不会自动创建原生验证码弹窗。viewTokens() 返回普通数据：业务 UI 需绑定这些值，主题变化时重新计算；hapticFeedback 为 true 时才调用系统震动 API。使用共享 Web 组件则由它应用样式和触觉反馈。

HarmonyOS NEXT

const client = new RozeCaptchaClient({
  baseUrl: 'https://pink.ya.wang', publicKey: publicKey,
  scene: 'login', clientId: bundleName, language: 'zh-CN',
  product: 'popup', hapticFeedback: true,
  appearance: new RozeCaptchaAppearance('auto', '#167d50', 8),
})
const tokens = client.viewTokens(isSystemDark)
const webOptions = client.webOptions()

ArkUI 自绘界面绑定 tokens；已有 ArkWeb 容器可使用 webOptions 初始化共享 Web 组件。SDK 不自动创建 ArkUI 验证弹窗。

微信 / 支付宝 / 抖音小程序

const { createWechatCaptchaClient } = require('./sdk/wechat')
const client = createWechatCaptchaClient({
  baseUrl: 'https://pink.ya.wang/api/captcha', publicKey,
  scene: 'login', clientId: appId, language: 'zh-CN', product: 'popup',
  appearance: { theme: 'auto', primaryColor: '#167d50', borderRadius: 8 },
  challengeMode: 'smart', hapticFeedback: true,
  requestTimeoutMs: 12000, configRetries: 1,
})
this.setData({ captchaPresentation: client.presentation, captchaTokens: client.viewTokens(isSystemDark) })
// 在 WXML/AXML/TTML 中绑定背景色、文字色、圆角和主按钮颜色。
// 产品模式/交互事件由本地组件实现，不能仅设置数据后就认为已渲染验证码。

支付宝换用 createAlipayCaptchaClient，抖音换用 createDouyinCaptchaClient，其他配置相同。传输层不会绘制题图，需使用原生界面完成交互；不能将这些包宣传为内置完整 UI。

TypeScript 自定义界面

import { createCaptchaClient } from './sdk/client-config'
const client = createCaptchaClient({
  baseUrl: 'https://pink.ya.wang', publicKey,
  scene: 'login', clientType: 'web', clientId: 'web',
  language: 'zh-CN', product: 'popup',
  appearance: { theme: 'auto', primaryColor: '#167d50', borderRadius: 8 },
  request: { timeoutMs: 12000, maxAttempts: 2 },
})
// 自绘界面读取 client.presentation。
// 共享 Web UI：RozeCaptcha.init({ container: '#captcha', ...client.webOptions(), onSuccess })
const challenge = await client.createChallenge()

captcha-public.ts 为生成的低阶 API；新代码优先使用 client-config.ts，避免将展示字段放进生成的请求结构。服务端 Node SDK 没有用户界面，不接受主题参数，仍负责消费 Proof 和判断联合验证结果。

必须由服务端处理

前端不能设置放行结果、跳过交互后伪造成功、降低风控阈值、延长凭证寿命或允许重放。只有业务后端核验得到 decision=allow 且 verification=passed 才执行登录/注册等操作。用户取消、网络超时、配置错误都不代表通过。

原生 WebView 接入应加载可信的随包/自托管 Web SDK，使用 JSON 序列化传参，限制页面跳转和消息来源，验证完整 Proof 后再交给业务后端；不要拼接未转义的 HTML/JS 或把 Server Key 放在客户端。