腾讯刷掌移动端（H5）SDK接口文档

面向对象：接入方前端 / H5 开发工程师

本文档帮助您在浏览器（含移动端 WebView）中接入刷掌采集能力。SDK 所需的用户 Token 由您的后端调用 CreateSdkUserToken 签发。

版本更新记录

版本号	发布日期	更新内容
v1.4.0	2026-10-09	识别 (1:N) 适配后端 v1.4：识别模式 `customHeaders.AppId` 必填，`search_rgb_palm` 请求体携带该 `AppId`，掌图 / 视频按 `AppId` 加密；`token` 可传空串（网关按 `AppId` 匿名放行，为空时不发送 `Authorization`），传了时须与 `AppId` 属于同一应用；`userId` 可不传。注册 / 1:1 仍需 `token`
v1.3.0	2026-09-14	日志上报对齐 palmreport 新契约：终态 trace（成功/取消/失败）始终上报，`enableLogReport` 仅控制加密现场图/视频诊断副本；诊断媒体预签名迁移至 `create_tmp_obj`（请求体携带 `AppId`）；桌面浏览器横向窗口不再判定为横屏取消
v1.2.0	2026-08-18	`RecognitionData.sessionId`；识别 / 核验启用 `CheckAppQuality`；移除 `Params.baseUrl`（API 地址由 SDK Host 部署决定）
v1.1.0	2026-08-16	对齐 PalmX Web SDK 对外面：`Params` / `Result` / `enableManager` / `enableImageOnly`；`VerificationData.sessionId`；管理页方向约束与 `get_palm` `10021` → 空手掌
v1.0.0	2026-07-20	PalmX 线首发

从 v1.3 升级请参阅文末「从 v1.3 升级到 v1.4」。

简介

Tencent Palm Mobile Manager Web SDK 是 PalmX 掌纹生物识别能力的 Web 平台实现，支持注册、核验 (1:1)、识别 (1:N) 三种模式。采集与算法在浏览器内通过 iframe + WebAssembly 完成；SDK 部署在独立的 SDK Host 域名下，宿主页通过一行 <script src> 或 npm 包即可接入。

核心模块

SDK 由两大核心模块构成：管理模块与采集模块。

管理模块

掌纹管理引导页（enableManager = true，默认），主要负责：

掌纹状态 — 查询左右手注册状态（get_palm），支持删除已注册手掌
业务流程 — 支持注册、识别 (1:N)、核验 (1:1) 三种模式入口
界面交互 — 展示操作引导、处理结果、错误提示与重试
结果处理 — 在 SDK 内展示采集结果；大部分业务错误留在 SDK 内重试
结果回调 — 仅在关键错误（参数非法、Token 失效、网关认证失败、用户不存在）或用户主动退出时回调宿主页

PalmX 管理模块不负责在 SDK 内创建用户（无 userName / phoneNo 入参）。用户须已由您的服务端在 PalmXAI Platform 侧就绪；Token 通过 CreateSdkUserToken 签发。应用 ID 不是独立入参，统一经 customHeaders.AppId 传入（识别 (1:N) 必填）。

采集模块

手掌信息采集（enableManager = false 时直入；管理模块内部也会调用同一套采集能力）：

相机采集 — 通过 navigator.mediaDevices.getUserMedia 唤起摄像头，提供实时预览
AI 处理 — 内置掌纹检测、质量评估、活体动作判断等算法能力（wasm 推理）
交互引导 — 引导用户完成「张开手掌」「握拳」等动作
数据上报 — 掌纹图像 AES-128-GCM 加密后上传；默认会采集并上传活体视频。客户端无法录制 → ErrLivenessVideoCaptureFailed (10105)；服务端判定视频不合格 → ErrLivenessVideoFailed (10102)；上传 / 网络失败 → ErrNetwork (10500)
仅图模式 — enableImageOnly = true 时跳过视频上传与云端 register / search / compare，直接返回加密后的 ImageData
日志上报 — 每次会话的终态 trace（成功 / 取消 / 失败）始终上报至 palmreport 日志通道，用于统计与排障；enableLogReport = true 时额外上传加密现场图 / 视频诊断副本（见 Params.enableLogReport）
方向约束 — 触屏移动设备转至横屏会作废本次采集（按 10002 用户取消处理）；桌面浏览器的窗口方向不影响采集

功能特性

多种模式：支持注册、核验 (1:1)、识别 (1:N)。
优化的 AI 算法：检测配准、活体判断、质量控制、动作判断经 WebAssembly 集成在 SDK 内。
模块化 UI：管理引导页与采集页提供预构建 UI。
Origin 隔离：采集 UI 与 wasm 运行在独立源的 iframe 内，通过 postMessage + 严格 origin 校验与宿主页解耦。
安全设计：掌纹数据上传前自动加密；Token 必须由服务端签发，禁止在前端硬编码平台密钥。

术语表 / 核心概念

【掌纹】单因子特征库
- 说明：仅记录【掌纹】单因子信息。浏览器摄像头无法采集【掌静脉】，本 SDK 仅采集【掌纹】单因子信息。
【掌纹+掌静脉】双因子特征库
- 说明：同时记录【掌纹】和【掌静脉】。用于专业设备录入的高安全标准；本 Web SDK 不采集掌静脉。

SDK Host

SDK 由服务方部署在独立域名（SDK Host）下。宿主页通过一行 <script src> 引入该域名下的 loader 即可接入。采集所需的 iframe、wasm、摄像头 UI 全部由 SDK Host 自动加载与托管，宿主页无需关心其内部构成。

https://open.intl.palm.tencent.com/palm/x/jssdk/loader/palm-mobile-manager.js —— 宿主页 <script src> 引入的入口
https://open.intl.palm.tencent.com/palm/x/jssdk/embed/ —— 采集 iframe 自动加载的页面（loader 会从自身 <script src> 推断地址，无需手动配置）

重要：SDK Host 必须与您的宿主页处于不同的 origin，postMessage 的 MessageEvent.origin 校验才有意义。loader 与 embed 同处一个 SDK Host。

工作流程

1. 获取用户令牌

您的服务端必须首先从 Tencent PalmXAI Platform 请求与终端用户 UserId 绑定的短时 Token（CreateSdkUserToken），再下发给客户端。

识别 (1:N) 不针对具体用户，可不获取 Token：token、userId 传空串，必须在 customHeaders 中传入 AppId，SDK 按该应用匿名识别。注册与核验 (1:1) 仍须先获取 Token。

生产环境的 Token 必须由您自己的后端签发，禁止把平台 api_key 写入前端。

2. 启动 SDK

SDK 模块	说明
管理模块	`enableManager = true`（默认）。展示管理引导页，用户交互后再进入采集；结果多在 SDK 内处理
采集模块	`enableManager = false`。直入摄像头采集，宿主页自行根据完整 `Result` 分发业务

3. 自动化流程

管理模块会自动完成：查询掌纹状态、展示引导与结果页、按模式调用采集、在 SDK 内提示重试。

采集模块采完即通过 Promise / callback 返回完整 Result（含成功时的 data）。

4. 获取回调

同一时刻只允许一个会话；并发调用会立即以 ErrSdkRuntime (10007) 拒绝。

管理模块：宿主页主要收到用户退出（10002）与关键透传码（见下方「回调结果码」）；成功业务数据通常留在 SDK 结果页内展示。
采集模块：宿主页需自行处理完整结果码表。

运行环境要求

项	要求
协议	HTTPS（`localhost` 例外）。浏览器 `getUserMedia` 强制要求安全上下文。
浏览器	● 桌面：Chrome / Edge ≥ 88，Firefox ≥ 90，Safari ≥ 14 ● 移动：iOS Safari ≥ 14，Android Chrome ≥ 88 ● 必需能力：`MediaDevices.getUserMedia`、`postMessage`、ES2020、WebAssembly
iframe 权限	SDK 会自动在 iframe 上设置 `allow="camera; microphone"`。若宿主页自身位于第三方 iframe 内，需在外层逐级放行相机权限。
Node/构建（仅 npm 接入）	Node.js ≥ 18

集成步骤

前置条件

SDK Host 地址：https://open.intl.palm.tencent.com，产物路径为 /palm/x/jssdk/。
HTTPS：SDK Host 与宿主页均需 HTTPS（localhost 例外）。
用户与 Token（注册 / 核验）：终端用户已在平台侧就绪；由您的后端调用 CreateSdkUserToken 下发 Token。
应用 ID（识别 (1:N)）：准备好您在 PalmXAI Platform 上的应用 ID（AppId），识别时经 customHeaders.AppId 传入。
隐私授权：SDK 内部不会弹出隐私协议，也不记录用户是否同意。请在调用 PalmMobileManager.start 之前，由您的页面获得用户的明确同意。

`<script>` 接入

引入 Loader
```

<script src="https://open.intl.palm.tencent.com/palm/x/jssdk/loader/palm-mobile-manager.js"></script>
```
UMD 产物在 window.PalmMobileManager 命名空间下暴露：PalmMobileManager 类，以及 Mode / PalmDirection / ResultCode。

简要调用示例

<script>
  const { PalmMobileManager, Mode } = window.PalmMobileManager;

  const params = {
    token: USER_TOKEN,
    userId: USER_ID,
    // mode: Mode.Registration,           // 默认 registration
    // mode: 'verification',              // 核验：userId 为 1:1 比对目标
    // mode: 'recognition',               // 识别 (1:N)：customHeaders.AppId 必填
    // palmDirection: 'palm_direction_unspecified',
    // enableManager: true,               // false = 直入采集
    // enableImageOnly: false,
    // enableLogReport: false,            // true = 额外上传加密诊断副本
    // customHeaders: { AppId: APP_ID },  // 应用 ID：识别必填，其余模式用于诊断副本上传
  };

  PalmMobileManager.start(params, (r) => {
    console.log('[PalmMobileManager]', r);
  }).then((result) => {
    console.log('final:', result);
  });
</script>

零配置：loader 以自身 <script src> 的 origin 作为 embed 站点地址。只要 loader 与 embed 部署在同一 SDK Host，宿主页无需额外配置。

npm 接入

pnpm add palm-mobile-manager

import { PalmMobileManager, Mode, PalmDirection } from 'palm-mobile-manager';

const result = await PalmMobileManager.start({
  token: USER_TOKEN,
  userId: USER_ID,
  // mode: Mode.Verification,
  // palmDirection: PalmDirection.Left,
  // enableManager: false,
});

console.log(result);

识别 (1:N) 调用示例

识别模式不针对具体用户：token、userId 传空串，AppId 必须通过 customHeaders 传入，缺失时立即返回 ErrInvalidParams (10001)。建议 enableManager = false，宿主页才能拿到完整的 RecognitionData。

import { PalmMobileManager, Mode, ResultCode } from 'palm-mobile-manager';

const result = await PalmMobileManager.start({
  token: '',                        // 可传空串：网关按 AppId 匿名放行，不发送 Authorization
  userId: '',                       // 1:N 不针对具体用户（TS 类型要求字段存在，传空串即可）
  mode: Mode.Recognition,
  customHeaders: { AppId: APP_ID }, // 必填：写入 search_rgb_palm 请求体，并作为掌图 / 视频加密因子
  enableManager: false,
});

if (result.code === ResultCode.Success) {
  // 命中用户的 userId / score / sessionId。
  // 请把 sessionId 交给您的服务端核对识别结果，不要仅凭 userId 判定身份。
  console.log(result.data);
}

若同时传了 token，该 Token 必须与 AppId 属于同一应用，否则后端返回 2060205（映射为 10012）。

本地联调

宿主页 <script src> 直接指向 SDK Host 即可。宿主页可跑在 http://localhost，摄像头由 SDK Host 的 HTTPS iframe 调起：

<script src="https://open.intl.palm.tencent.com/palm/x/jssdk/loader/palm-mobile-manager.js"></script>

联调用的测试 Token 可由您的测试后端调用 CreateSdkUserToken 签发，或参考文末「测试环境快速启动」。

API 参考

`PalmMobileManager.start(params, callback?)`

启动一次采集 / 管理流程，返回 Promise<Result>。callback 与 Promise 会拿到同一份 Result。同一时刻只允许一个会话；并发调用立即返回 ErrSdkRuntime (10007)。

位置参数	类型	必填	说明
`params`	`Params`	✅	业务参数，见下
`callback`	`(result: Result) => void`		可选回调；未传时 `Promise` 同样会 resolve 出同一份结果

`PalmMobileManager.back()`

向当前会话的 embed 发送后退指令（与界面返回键同语义）。无进行中会话时为空操作。

`PalmMobileManager.version`

静态字符串，SDK 版本号，当前为 1.4.0，与本文档的产品线版本一致。

Params

启动 SDK 时的配置参数对象。

提示：启动时仅做非空校验（注册 / 核验校验 token、userId；识别校验 customHeaders.AppId），不通过返回 code=10001。userId 推荐遵循下述格式，否则可能由后端映射为 10018。

各模式必填项

参数	注册	核验 (1:1)	识别 (1:N)
`token`	✅	✅	可传空串
`userId`	✅ 待注册用户	✅ 比对目标用户	可传空串
`customHeaders.AppId`	可选	可选	✅

身份参数

参数	类型	描述
`token`	`string`	用户身份令牌，用于授权本次 SDK 操作（由后端 `CreateSdkUserToken` 签发）。`recognition` 可传空串（匿名识别，按 `customHeaders.AppId` 检索）。
`userId`	`string`	用户唯一标识符。 • `registration`：待注册用户 • `verification`：1:1 比对目标用户（`CompareUserId`） • `recognition`：可不传（1:N 不针对具体用户）推荐格式：1–64 字符，仅 `[A-Za-z0-9_-]`，无空白。

可选参数

参数	类型	默认值	描述
`mode`	`Mode`	`Registration` (`'registration'`)	• `Mode.Registration` (`'registration'`) — 注册 • `Mode.Verification` (`'verification'`) — 核验 (1:1) • `Mode.Recognition` (`'recognition'`) — 识别 (1:N)
`palmDirection`	`PalmDirection`	`Unspecified`	• `PalmDirection.Unspecified` (`'palm_direction_unspecified'`) — 任意手 • `PalmDirection.Left` (`'left'`) — 强制左手 • `PalmDirection.Right` (`'right'`) — 强制右手
`enableManager`	`boolean`	`true`	`true` 启动管理模块；`false` 直入采集模块。
`enableImageOnly`	`boolean`	`false`	`true` 时仅返回加密掌图 `ImageData`，不上传视频、不调用 register / search / compare。
`enableLogReport`	`boolean`	`false`	`true` 时额外上传 AES-128-GCM 加密的现场图 / 视频诊断副本（经 `create_tmp_obj` 申请预签名 URL 后直传对象存储），用于问题排查。终态 trace 日志不受此开关控制，始终上报（统计基线）。
`customHeaders`	`Record<string, string>`	`{}`	自定义 HTTP 请求头。其中 `AppId`（key 大小写不敏感）为应用 ID： • `recognition` 必填；传了 `token` 时须与其所属应用一致——SDK 将其写入 `search_rgb_palm` 请求体，并作为掌图 / 视频加密因子，否则后端返回 `2060205`（映射为 `10012`） • 其余模式用于诊断副本上传（`create_tmp_obj`）注意：`customHeaders` 会原样附加到 SDK 的每个请求上。不要传 `Authorization`，它会覆盖 SDK 根据 `token` 生成的 `Bearer <token>`。Web 版无 `baseUrl`，请求始终发往 SDK Host 网关，由 `token` 鉴权。

与原生 SDK 的差异（H5 特点）：Web 版不暴露 baseUrl。API 服务地址由 embed / SDK Host 在部署时决定：默认同源相对路径 /palm/*（Ingress / 反向代理）；若页面 host 为 app.*，SDK 内部转写到同后缀 open.*。宿主页无法覆盖。若需连接不同环境的后端，请使用对应环境的 SDK Host。

与部分旧版 PalmX 文档的差异：无 userName / phoneNo / targetUserId；appId 与原生 SDK 一致经 customHeaders.AppId 传入。核验目标即为 userId。

Result

SDK 退出时通过回调 / Promise 返回的结果对象。

interface Result {
  code: number;
  message: string;
  data?: RegistrationData | RecognitionData | VerificationData | ImageData;
  traceId?: string;
}

属性	类型	描述
`code`	`number`	结果码，详见下方结果码列表。
`message`	`string`	描述信息，仅用于调试。
`data`	`ResultData` \| `undefined`	成功时的详细结果数据，形态由 `mode` / `enableImageOnly` 决定。
`traceId`	`string` \| `undefined`	请求链路 ID（失败时可能返回，便于排障）。

ResultData

interface RegistrationData {
  userId: string;
  /** 注册结果临时查询凭据（对齐 RegisterRgbPalmRsp.SessionId，TTL 约 2 小时） */
  sessionId?: string;
  /** 本次注册的手掌方向 */
  palmDirection?: PalmDirection;
}

interface RecognitionData {
  userId: string;
  score: number;
  palmDirection?: PalmDirection;
  /** 识别结果临时查询凭据（对齐 SearchRgbPalmRsp.SessionId，TTL 约 2 小时） */
  sessionId?: string;
}

interface VerificationData {
  isMatch: boolean;
  score: number;
  palmDirection?: PalmDirection;
  /** 比对结果临时查询凭据（对齐 CompareRgbPalmRsp.SessionId，TTL 约 2 小时） */
  sessionId?: string;
}

interface ImageData {
  /** 序列化后的采集 JSON（图片字段已 AES-128-GCM 加密） */
  payload: string;
}

sessionId 交由您的服务端调用 GetSessionResult 核对结果。

回调结果码（管理模块）

管理模块会自动处理采集中的大部分结果。宿主页在 enableManager = true 时，主要会收到以下结果码：

结果码	场景	处理建议
`10002`	用户主动退出（管理页根路径返回等）	按取消处理
`10001`	参数非法	校验必填项与 `mode` 等（如识别模式未传 `customHeaders.AppId`）
`10012`	Token 无效或过期；识别模式下 Token 与 `AppId` 不属于同一应用	重新获取 Token / 核对 `AppId`
`10021`	用户不存在（透传）	提示核对用户 / 重新登录
`10401`	网关认证失败	检查网关 JWT / 联系技术支持

管理页阶段（采集开始前）的 Token / 网关鉴权失败，SDK 会立即退出并回调；采集阶段鉴权失败时，管理模块先展示失败结果页，用户退出后再回调（结果码不变）。成功业务结果默认留在管理模块结果页；若宿主需要拿到完整成功 data，请使用采集模块（enableManager = false）。

完整结果码参考

说明：采集模块（enableManager = false）不会吞掉结果码，宿主页需自行分发。完整结果码如下：

点击展开查看所有结果码

通用结果码

结果码	枚举	开发说明
0	`Success`	操作成功
10000	`ErrUnknown`	未知错误
10001	`ErrInvalidParams`	参数无效，如识别模式未传 `customHeaders.AppId`（管理模块会回调）
10002	`ErrUserCancelled`	用户取消（管理模块会回调）
10003	`ErrCameraPermissionDenied`	相机权限被拒绝
10004	`ErrCameraInitFailed`	相机初始化失败
10005	`ErrCameraPreviewUnsupported`	不支持的相机预览尺寸
10006	`ErrSdkInitFailed`	SDK 初始化失败（含 wasm）
10007	`ErrSdkRuntime`	SDK 运行时错误（含「另一个会话进行中」）
10008	`ErrAcquisitionTimeout`	采集超时（30 秒）
10012	`ErrUserTokenInvalid`	Token 无效或已过期（会回调 / 可能立即退出）
10016	`ErrLicenseValidationFailed`	授权证书验证失败
10018	`ErrUserIdInvalid`	用户 ID 格式不正确
10020	`ErrAppDisabled`	应用被禁用
10021	`ErrUserNotExist`	用户不存在（管理模块会回调；管理页 `get_palm` 命中时按空手掌处理）

注册模式结果码

结果码	枚举	开发说明
10100	`ErrLivenessFailed`	活体检测失败
10101	`ErrQualityFailed`	质量检查失败
10102	`ErrLivenessVideoFailed`	活体视频验证失败（服务端判定）
10103	`ErrAlreadyBind`	该手掌已注册
10104	`ErrHighSimilarity`	与已有用户高度相似
10105	`ErrLivenessVideoCaptureFailed`	客户端本地活体视频录制失败（浏览器不支持 / 非安全上下文 / recorder 失活）

识别模式结果码

结果码	枚举	说明
10200	`ErrUserNotRecognized`	用户未识别

核验模式结果码

结果码	枚举	说明
10200	`ErrUserNotRecognized`	比对库中未找到待验证用户的掌纹特征（与识别模式共用该码）
10300	`ErrTargetUserNotFound`	待验证用户不存在
10301	`ErrTargetUserUnregistered`	待验证用户未注册掌纹
10302	`ErrTargetUserPalmDirectionUnregistered`	待验证用户未注册当前手掌方向

网络结果码

结果码	枚举	说明
10401	`ErrUnauthorized`	网关未认证访问（会回调 / 可能立即退出）
10500	`ErrNetwork`	网络错误（含未映射的后端业务码兜底）

架构

Host Page (您的业务页)
  └─ PalmMobileManager.start(params, callback?)
       └─ <iframe src="https://open.intl.palm.tencent.com/palm/x/jssdk/embed/" allow="camera; microphone">
            └─ Manager View → Acquisition View
                 └─ getUserMedia + wasm 推理 + Tencent PalmXAI Platform
       ←── postMessage { ns:'palm-mobile-manager', v:1, msg:{ type:'result', payload } } ──

Loader ↔ Embed 严格双向 origin 校验：宿主页的其它 iframe 无法伪造结果。
云端接口（非 enableImageOnly）：register_rgb_palm / search_rgb_palm / compare_rgb_palm；识别与核验请求会携带 CheckAppQuality: true。
日志通道：终态 trace（成功 / 取消 / 失败）始终上报 /palm/openai/palm/palmreport/logs（OTLP，report_source=3，device_sn 为浏览器持久化随机 ID）；enableLogReport = true 时另经 /palm/openai/palm/palmreport/create_tmp_obj（请求体携带 AppId）申请预签名 URL，直传加密现场图 / 视频诊断副本。SDK 在返回结果前等待日志队列收尾，宿主页销毁 iframe 不会截断最后一条 trace。

完整时序图（点击展开）

安全警告

生产环境安全要求

严禁在生产环境的浏览器代码中硬编码任何平台账户密钥！

浏览器代码对所有终端用户可见。所有涉及平台密钥的调用（如 CreateSdkUserToken）必须在您的服务端完成，浏览器只接收服务端下发的短期 Token。

正确做法（生产环境）：

识别 (1:N) 结果核对

识别 (1:N) 传入的 AppId 是应用标识而非密钥，可以放在前端；但匿名识别后浏览器回调里的 userId 可能被篡改，识别成功返回的 sessionId 应交给您的服务端核对结果（TTL 约 2 小时），不要仅凭浏览器回调中的 userId 判定身份。

会话唯一性

Web 端同一时刻只允许一个 SDK 会话。并发调用 PalmMobileManager.start() 会立即以 ErrSdkRuntime (10007) 拒绝，避免多 iframe 同时争抢摄像头。

测试环境快速启动

仅用于本地开发 / 内部测试 / 隔离 Demo。生产环境中 Token 必须由后端在用户会话内动态下发。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
  <title>刷掌 H5 测试页</title>
</head>
<body>
  <button id="startBtn">开始刷掌</button>
  <pre id="result"></pre>

  <script src="https://open.intl.palm.tencent.com/palm/x/jssdk/loader/palm-mobile-manager.js"></script>
  <script>
    // [仅供测试] 直接把后端签发的测试 Token 写在页面里
    const USER_TOKEN = 'sut_xxx';       // 注册 / 核验必填；识别可留空
    const USER_ID = 'YourUserId';       // 注册 / 核验必填；识别可留空
    const APP_ID = 'YourAppId';         // 识别 (1:N) 必填
    const MODE = 'registration'; // 'registration' | 'verification' | 'recognition'

    const { PalmMobileManager } = window.PalmMobileManager;
    const resultEl = document.getElementById('result');

    document.getElementById('startBtn').addEventListener('click', async () => {
      try {
        const result = await PalmMobileManager.start({
          token: USER_TOKEN,
          userId: USER_ID,
          mode: MODE,
          customHeaders: { AppId: APP_ID },
          enableManager: false, // 测试时建议直入采集，便于观察完整 Result
        });
        resultEl.textContent = JSON.stringify(result, null, 2);
      } catch (err) {
        resultEl.textContent = `Error: ${err?.code ?? ''} ${err?.message ?? err}`;
      }
    });
  </script>
</body>
</html>

从 v1.3 升级到 v1.4

v1.4 的对外变更集中在识别 (1:N)。只用注册和核验 (1:1) 的接入方，不改代码也能升级。

#	变化	影响	是否需要改代码
1	识别 (1:N) 必须传 `customHeaders.AppId`	破坏性：不传会直接返回 `10001`	✅ 用识别的必须改
2	识别时掌图和视频按 `AppId` 加密	SDK 内部处理，后端按请求体中的 `AppId` 解密	❌ 只要传了正确的 `AppId`
3	识别可以不传 `token`，`userId` 也可以不传	可选：不用再为识别签发 Token	建议改
4	`RegistrationData` 新增 `sessionId`、`palmDirection`	新增字段，不影响老代码	❌ 按需使用
5	`PalmMobileManager.version` 从 `0.0.1` 改为 `1.4.0`	只影响按版本号判断的逻辑	视情况
6	采集阶段 Token 失效时先展示失败结果，再回调宿主	管理模块下回调会晚一点到	❌

识别调用的代码对比：

 const result = await PalmMobileManager.start({
-  token: userToken,          // v1.3：识别也要先签发 Token
-  userId: 'placeholder',     // v1.3：校验要求非空
+  token: '',                 // v1.4：识别可传空串
+  userId: '',
   mode: Mode.Recognition,
+  customHeaders: { AppId: APP_ID },   // v1.4：识别必填
   enableManager: false,
 });

升级检查清单：

引用 v1.4.0 的 loader 或 npm 包
所有 mode = recognition 的调用都传了 customHeaders.AppId
AppId 是当前环境（测试 / 正式）对应的应用 ID
（可选）删掉识别前签发 Token、填占位 userId 的逻辑
识别成功后由服务端用 sessionId 核对结果
如有按 version === '0.0.1' 判断的逻辑，同步修改
注册、核验、识别三种模式各回归一次

常见问题：

现象	可能原因	处理
识别启动后立刻返回 `10001`	没有传 `customHeaders.AppId`，或传了空串	补上 `AppId`
识别返回 `10012`	`AppId` 在当前环境不存在（例如把测试环境的 ID 用到了正式环境）；或者传了 Token，但 Token 失效或不属于该应用	核对 `AppId` 与环境；识别时可以直接不传 Token
识别一直返回 `10200`（未识别到用户）	`AppId` 填成了另一个应用，用户掌纹不在该应用的库里	确认 `AppId` 和注册时用的是同一个应用
注册 / 核验返回 `10001`	这两种模式仍然要求 `token` 和 `userId` 非空	按原方式传入

后续步骤与支持

服务端接口：Token 签发、掌纹查询 / 删除、识别结果核对见 KYC 开放 API 对接文档
原生 App 接入：Android / iOS / Flutter 见移动端（App）SDK
获取技术支持：集成问题请联系您的技术支持代表

版本更新记录​

简介​

核心模块​

管理模块​

采集模块​

功能特性​

术语表 / 核心概念​

SDK Host​

工作流程​

1. 获取用户令牌​

2. 启动 SDK​

3. 自动化流程​

4. 获取回调​

运行环境要求​

集成步骤​

前置条件​

<script> 接入​

npm 接入​

识别 (1:N) 调用示例​

本地联调​

API 参考​

PalmMobileManager.start(params, callback?)​

PalmMobileManager.back()​

PalmMobileManager.version​

Params​

各模式必填项​

身份参数​

可选参数​

Result​

ResultData​

回调结果码（管理模块）​

完整结果码参考​

通用结果码​

注册模式结果码​

识别模式结果码​

核验模式结果码​

网络结果码​

架构​

安全警告​

生产环境安全要求​

识别 (1:N) 结果核对​

会话唯一性​

测试环境快速启动​

从 v1.3 升级到 v1.4​

后续步骤与支持​