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

面向对象：接入方 Android / iOS / Flutter 开发工程师

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

版本更新记录

版本号	发布日期	更新内容
v1.4.0	2026-10-13	识别 (1:N) 对齐 H5 SDK v1.4.0 契约：识别模式 `customHeaders` 中的 `AppId` 必填（缺失返回 `10001`），SDK 将其写入 `search_rgb_palm` 请求体，掌图 / 活体图 / 活体视频按 `AppId` 加密（注册 / 核验仍按 `userId`）；`token`、`userId` 可传空串，为空时不发送 `Authorization`；Flutter `Params` 的 `token` / `userId` 默认空串；结果码补充 `10020` / `10302`
v1.2.0	2026-08-18	`RecognitionData.sessionId`（对齐 `SearchRgbPalmRsp.SessionId`，临时查询凭据，TTL 约 2 小时，可用于服务端核对识别结果）
v1.0.0	2026-07-20	首发

原生 SDK 没有单独发布 v1.3。从 v1.2 升级请参阅文末「从 v1.2 升级到 v1.4」。

简介

Tencent Palm Mobile Manager SDK 提供了一套完整的移动端掌纹生物识别解决方案，支持注册、核验 (1:1) 与识别 (1:N) 三种模式。内置 AI 算法与相机采集能力，让您的应用能轻松集成掌纹生物识别能力。

模块概览

SDK 提供采集模块，负责端侧的掌纹采集与算法处理：

相机采集 — 唤起摄像头，提供实时预览画面
AI 处理 — 内置掌纹检测、质量评估、活体动作判断等算法能力
交互引导 — 引导用户完成「张开手掌」「握拳」等动作
数据上报 — 将采集数据加密上传至服务器（视频按需上传）
结果回调 — 将采集结果（成功、失败、算法输出）回调给您的应用，后续 UI 与业务由您接管

功能特性

多种模式：支持注册、核验 (1:1) 和识别 (1:N) 三种模式。
跨平台支持：提供开箱即用的 Android、iOS 与 Flutter 版本 SDK。
优化的 AI 算法：SDK 内部直接集成检测配准、活体判断、质量控制、动作判断等算法。
安全设计：所有掌纹数据在传输至服务器前均经过自动加密。

工作流程

1. 获取用户令牌

Token 必须由您的后端服务器签发。您的后端调用 Tencent PalmXAI Platform 的 CreateSdkUserToken 接口，传入终端用户的 UserId，得到一个仅属于该用户且短时有效的 Token，再下发给客户端使用。

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

2. 启动 SDK

3. 获取回调

您的应用会在回调中收到 Result，其中 code 字段对应本文档中的结果码，data 字段包含对应模式的详细采集数据（注册 / 识别 / 核验）。

时序图

开发环境要求

为确保 SDK 的稳定运行与兼容性，请确保您的开发环境满足以下最低要求：

平台	要求
Android	● JDK：17 或更高版本 ● Android Gradle Plugin (AGP)：8.5 或更高版本 ● Android Studio：Koala \| 2024.1.1 或更高版本（以匹配 AGP 要求） ● minSdkVersion：24 ● compileSdkVersion / targetSdkVersion：34+
iOS	● Xcode：16.0 或更高版本 ● Minimum Deployment Target：iOS 13.0
Flutter	● Flutter SDK：3.25.0 或更高版本

集成步骤

SDK 软件包：请联系交付人员获取

以下目录结构均以软件包目录结构为准。

前置条件

授权证书：您需要向我们提供您应用的 Android ApplicationId 和 iOS BundleId，以便我们为您生成和绑定 SDK 算法运行时需要的授权证书。

提示：用于 Demo 开发。如果您只是为了开发和测试，可以将应用的 ID 设置为符合 com.tencent.palm.* 通配符的格式（例如 com.tencent.palm.demo）。此方式可以免去申请授权证书的步骤。
用户与 Token（注册 / 核验）：终端用户已在平台侧就绪；由您的后端调用 CreateSdkUserToken 下发 Token。
应用 ID（识别 (1:N)）：准备好您在 PalmXAI Platform 上的应用 ID（AppId），识别时经 customHeaders 传入。
隐私授权：SDK 内部不会弹出隐私协议，也不记录用户是否同意。请在调用 PalmMobileManager.start 之前，由您的 App 获得用户的明确同意。

Android 集成

导入 LocalMavenRepo 仓库

将 Android/repo 拷贝至您的项目下，例如 [YOUR_PROJECT]/app/repo。

配置 app/build.gradle 文件

// ...
repositories {
    // ... 其他仓库
    maven {
        name = "LocalMavenRepo"
        url = uri("${projectDir}/repo") // 确保路径正确
    }
}

dependencies {
    // ... 其他依赖
    implementation "com.tencent.palm:PalmMobileManager:1.4.0"
}

简要调用示例

PalmMobileManager.Params params = new PalmMobileManager.Params.Builder(
        USER_TOKEN,
        USER_ID)
    // 设置模式（可选，默认为 REGISTRATION）
    // .setMode(PalmMobileManager.Mode.VERIFICATION)
    // 识别 (1:N)：token / userId 传空串，AppId 必填（见「识别 (1:N) 调用示例」）
    // .setMode(PalmMobileManager.Mode.RECOGNITION)
    // .addCustomHeader("AppId", APP_ID)
    // 限定采集的手掌方向（可选，默认 INVALID = 自动识别左右手）
    // .setPalmDirection(PalmDirection.LEFT)
    // 您也可以将 SDK 指向自己部署的 Tencent PalmXAI Platform。
    // .setBaseUrl(BASE_URL)
    // 可以自定义 HTTP 请求头来访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）。
    // 注意：Authorization 会覆盖 SDK 根据 token 生成的 "Bearer <token>"，仅在您自建的网关自行鉴权
    // 并向 Tencent PalmXAI Platform 转发用户 Token 时使用；直连平台时不要传
    // .addCustomHeader("Authorization", "YOUR_JWT_TOKEN")
    .build();

PalmMobileManager.start(this, params, result -> {
    // TODO: 您需要自己对 result 的结果进行分析并驱动业务逻辑
    // 请参考下方结果码映射关系，data 中包含了 result 的详细信息
    Log.i("PalmMobileManager", result.toString());
});

参考示例工程

详见软件包中的 Android/example 工程。

iOS 集成

导入 Framework

将 iOS/Frameworks/PalmMobileManager.xcframework 拖入您的 Xcode 项目，并确保在 "General" → "Frameworks, Libraries, and Embedded Content" 中设置为 "Embed & Sign"。
配置相机权限

在 Info.plist 文件中添加 Privacy - Camera Usage Description（相机权限使用描述），并填写对用户可见的说明文字。

简要调用示例

let params = PalmMobileManagerParams(
    token: token,
    userId: userId
)
// 设置模式（可选，默认为 registration）
// params.mode = .verification
// 识别 (1:N)：token / userId 传空串，AppId 必填（见「识别 (1:N) 调用示例」）
// params.mode = .recognition
// params.addCustomHeader(withKey: "AppId", value: appId)
// 限定采集的手掌方向（可选，默认 .invalid = 自动识别左右手）
// params.palmDirection = .left
// 您也可以将 SDK 指向自己部署的 Tencent PalmXAI Platform。
// params.baseUrl = BASE_URL
// 可以自定义 HTTP 请求头来访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）。
// 注意：Authorization 会覆盖 SDK 根据 token 生成的 "Bearer <token>"，仅在您自建的网关自行鉴权
// 并向 Tencent PalmXAI Platform 转发用户 Token 时使用；直连平台时不要传
// params.addCustomHeader(
//     withKey: "Authorization",
//     value: "YOUR_JWT_TOKEN"
// )
PalmMobileManager.start(
    from: controller,
    params: params,
    completion: { result in
        // TODO: 您需要自己对 result 的结果进行分析并驱动业务逻辑
        // 请参考下方结果码映射关系，data 中包含了 result 的详细信息
        print("PalmMobileManager: \(result.code): \(result.message): \(String(describing: result.data))")
    }
)

参考示例工程

详见软件包中的 iOS/example 工程。

Flutter 集成

导入插件

将 flutter/palm_mobile_manager 放置于项目下的 packages 目录（如果不存在请创建）。

[YOUR_FLUTTER_APP]/
├── packages/
│   └── palm_mobile_manager/  <-- 插件目录
├── lib/
...
└── pubspec.yaml

添加依赖

在 [YOUR_FLUTTER_APP]/pubspec.yaml 中添加本地路径依赖：

dependencies:
  flutter:
    sdk: flutter

  # ... 其他依赖
  palm_mobile_manager:
    path: packages/palm_mobile_manager

添加 Android LocalMavenRepo 路径

在 [YOUR_FLUTTER_APP]/android/build.gradle.kts（或 build.gradle）中添加 Maven 仓库路径：

allprojects {
    repositories {
        google()
        mavenCentral()
        // add next config to local maven repo
        maven {
            url = uri(rootDir.resolve("../packages/palm_mobile_manager/android/repo"))
        }
    }
}

iOS 配置相机权限

在 [YOUR_FLUTTER_APP]/ios/Runner/Info.plist 中添加 NSCameraUsageDescription：
```
<key>NSCameraUsageDescription</key>
<string>需要相机权限以进行掌纹扫描。</string>
```

简要调用示例

final params = Params(
  token: _tokenController.text,
  userId: _userIdController.text,
  // 设置模式（可选，默认为 Mode.registration）
  // mode: Mode.verification,
  // 识别 (1:N)：token / userId 可不传，AppId 必填（见「识别 (1:N) 调用示例」）
  // mode: Mode.recognition,
  // 限定采集的手掌方向（可选，默认 PalmDirection.invalid = 自动识别左右手）
  // palmDirection: PalmDirection.left,
  // 您也可以将 SDK 指向自己部署的 Tencent PalmXAI Platform。
  // baseUrl: BASE_URL,
  // 自定义请求头：所有 key 放在同一个 Map 中，按需保留
  // customHeaders: {
  //   // 应用 ID：识别 (1:N) 必填；SDK 内部使用，不作为请求头发送
  //   'AppId': appId,
  //   // 访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）。会覆盖 SDK 根据 token 生成的
  //   // "Bearer <token>"，仅在您自建的网关自行鉴权并转发用户 Token 时使用；直连平台时不要传
  //   'Authorization': 'YOUR_JWT_TOKEN',
  // },
);

Result result;
try {
  result = await _palmMobileManager.start(params);
  print('Success! Result from native: $result');
} catch (e) {
  result = Result(code: -1, message: e.toString());
  print('Error! Failed to start: $e');
}

参考示例工程

详见软件包中的 flutter/palm_mobile_manager/example 工程。
首次打开示例工程的 iOS 项目（重要）

example/ios/Pods/、example/ios/Flutter/Generated.xcconfig、.dart_tool/ 等均为本地生成产物，软件包中不会包含。直接用 Xcode 打开 example/ios/Runner.xcworkspace 会报：
```
Unable to load contents of file list:
'/Target Support Files/Pods-Runner/Pods-Runner-frameworks-Release-input-files.xcfilelist'
```
这是 Flutter plugin 工程的标准现象（与 SDK 版本无关）。请先在 flutter/palm_mobile_manager/ 目录下依次执行以下三步（pod install 依赖前一步生成的 Generated.xcconfig，顺序不可颠倒）：
```
flutter pub get                       # 插件本体依赖
(cd example && flutter pub get)       # 生成 example 的 .symlinks 与 ios/Flutter/Generated.xcconfig
(cd example/ios && pod install)       # 生成 Pods 与 xcfilelist
```
完成后再用 Xcode 打开 example/ios/Runner.xcworkspace 即可正常编译。

若 pod install 报 Unable to find a specification for ...，说明本地 CocoaPods spec repo 落后于 Podfile.lock，改用 pod install --repo-update 重试即可。

API 参考

识别 (1:N) 调用示例

识别模式不针对具体用户：token、userId 传空串，AppId 必须通过 customHeaders 传入，缺失时立即返回 10001。识别成功后，RecognitionData 返回命中用户的 userId、score 与 sessionId。

// Android
PalmMobileManager.Params params = new PalmMobileManager.Params.Builder("", "")
    .setMode(PalmMobileManager.Mode.RECOGNITION)
    .addCustomHeader("AppId", APP_ID)
    .build();

// iOS
let params = PalmMobileManagerParams(token: "", userId: "")
params.mode = .recognition
params.addCustomHeader(withKey: "AppId", value: appId)

// Flutter
final params = Params(
  mode: Mode.recognition,
  customHeaders: {'AppId': appId},
);

若同时传了 token，该 Token 必须与 AppId 属于同一应用，否则返回 10012。

Params

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

提示：启动 SDK 时仅进行非空、非法校验（注册 / 核验校验 token、userId；识别校验 customHeaders 中的 AppId），不通过返回 code=10001。接入方应遵循下述格式要求，否则会在运行时出现网络相关错误。

各模式必填项

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

身份参数

参数	类型	描述
`token`	`String`	用户身份令牌，用于授权本次 SDK 操作（由后端 `CreateSdkUserToken` 签发）。`RECOGNITION` 可传空串（匿名识别，按 `customHeaders` 中的 `AppId` 检索），为空时不发送 `Authorization` 请求头。
`userId`	`String`	本次操作的目标用户唯一标识。 • `REGISTRATION`：待注册掌纹的用户 • `VERIFICATION`：待比对的已注册用户（1:1） • `RECOGNITION`：可传空串（1:N 不针对具体用户）格式要求：1-64 字符，仅支持 ASCII 字母（A-Z、a-z）、数字（0-9）、短横线（-）和下划线（_），不允许空格及其他空白字符。

可选参数

参数	类型	默认值	描述
`mode`	`Mode`	`REGISTRATION`	业务模式。可选值： • `REGISTRATION` - 注册模式 • `VERIFICATION` - 核验模式 (1:1) • `RECOGNITION` - 识别模式 (1:N)
`baseUrl`	`String`	`https://open.intl.palm.tencent.com`	API 服务地址。
`customHeaders`	`Map<String, String>`	-	自定义 HTTP 请求头，用于访问您配置的 `BaseUrl` 所对应的网关（如传递 JWT Token）。其中 `AppId`（key 大小写不敏感，前后空白会被去掉）为应用 ID，不作为请求头发送： • `RECOGNITION` 必填，缺失返回 `10001`；传了 `token` 时须与其所属应用一致。SDK 将其写入 `search_rgb_palm` 请求体，并作为掌图 / 视频加密因子 • 其余模式用于诊断日志上报注意：除 `AppId` 外的 key 原样作为请求头发送，`Authorization` 会覆盖 SDK 根据 `token` 生成的 `Bearer <token>`。仅在您自建的网关自行鉴权、并向 Tencent PalmXAI Platform 转发用户 Token 时传入；直连平台时不要传。
`palmDirection`	`PalmDirection`	`INVALID`	限定采集的手掌方向。可选值： • `INVALID` - 自动识别左右手（默认） • `LEFT` - 仅采集左手 • `RIGHT` - 仅采集右手

Result

SDK 退出时通过回调返回的结果对象。您需要自行解析 result：code 字段对应下方结果码，data 字段包含详细信息。

属性	类型	描述
`code`	`int`	结果码，详见下方结果码列表。
`message`	`String`	描述信息，仅用于调试。
`data`	`Data?`	与当前模式对应的数据体：`RegistrationData` / `RecognitionData` / `VerificationData`；非成功场景为 `null`。识别成功时 `RecognitionData.sessionId` 为临时查询凭据（TTL 约 2 小时），可交由服务端调用 GetSessionResult 核对识别结果是否被篡改。

结果码参考

通用结果码

结果码	开发说明
0	操作成功
10000	未知错误
10001	参数无效（如识别模式未传 `AppId`）
10002	用户取消采集操作
10003	相机权限被拒绝
10004	相机初始化失败
10005	不支持的相机预览尺寸
10006	SDK 初始化失败
10007	SDK 运行时错误
10008	采集超时（30 秒超时）
10012	Token 无效或已过期；识别模式下 Token 与 `AppId` 不属于同一应用
10016	授权证书验证失败
10018	用户 ID 格式不正确
10020	应用已被禁用
10021	用户不存在

注册模式结果码

结果码	开发说明
10100	活体检测失败
10101	质量检查失败
10102	活体视频验证失败
10103	该手掌已注册
10104	与已有用户高度相似

识别模式结果码

结果码	说明
10200	未识别到已注册的掌纹（1:N 未命中）

核验模式结果码

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

网络结果码

结果码	说明
10401	网关未认证访问
10500	网络错误

安全警告

绝不要将 Tencent PalmXAI Platform 的 api_key 写入客户端代码。 Token 签发（CreateSdkUserToken）必须在您的后端完成，客户端只接收后端下发的、针对当前用户的短期 Token。

识别 (1:N) 传入的 AppId 是应用标识而非密钥，可以放在客户端；识别成功返回的 sessionId 应交给您的服务端核对结果，不要仅凭客户端回调中的 userId 判定身份。

从 v1.2 升级到 v1.4

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

#	变化	影响	是否需要改代码
1	识别 (1:N) 必须传 `customHeaders` 中的 `AppId`	破坏性：不传会直接返回 `10001`	✅ 用识别的必须改
2	识别时掌图和视频按 `AppId` 加密	SDK 内部处理，后端按请求体中的 `AppId` 解密	❌ 只要传了正确的 `AppId`
3	识别可以不传 `token`，`userId` 也可以不传	可选：不用再为识别签发 Token	建议改

识别调用的代码对比：

Android

-PalmMobileManager.Params params = new PalmMobileManager.Params.Builder(userToken, "placeholder")
+PalmMobileManager.Params params = new PalmMobileManager.Params.Builder("", "")
     .setMode(PalmMobileManager.Mode.RECOGNITION)
+    .addCustomHeader("AppId", APP_ID)
     .build();

iOS

-let params = PalmMobileManagerParams(token: userToken, userId: "placeholder")
+let params = PalmMobileManagerParams(token: "", userId: "")
 params.mode = .recognition
+params.addCustomHeader(withKey: "AppId", value: appId)

Flutter

 Params(
-  token: userToken,
-  userId: 'placeholder',
   mode: Mode.recognition,
+  customHeaders: {'AppId': appId},
 )

升级检查清单：

替换为 v1.4.0 的 SDK 包（Android aar / iOS xcframework / Flutter 插件）
所有 RECOGNITION 模式的调用都在 customHeaders 中传了 AppId
AppId 是当前环境（测试 / 正式）对应的应用 ID
（可选）删掉识别前签发 Token、填占位 userId 的逻辑
识别成功后由服务端用 sessionId 核对结果
注册、核验、识别三种模式各回归一次

常见问题：

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

后续步骤与支持

查阅示例工程：强烈建议您在集成前，先编译并运行对应平台的示例工程，快速了解 SDK 的完整调用流程。
服务端接口：Token 签发、掌纹查询 / 删除、识别结果核对见 KYC 开放 API 对接文档。
H5（Web）接入：见移动端（H5）SDK。
获取技术支持：如果在集成过程中遇到任何问题，请联系您的技术支持代表。

版本更新记录​

简介​

模块概览​

功能特性​

工作流程​

1. 获取用户令牌​

2. 启动 SDK​

3. 获取回调​

时序图​

开发环境要求​

集成步骤​

SDK 软件包：请联系交付人员获取​

前置条件​

Android 集成​

iOS 集成​

Flutter 集成​

API 参考​

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

Params​

各模式必填项​

身份参数​

可选参数​

Result​

结果码参考​

通用结果码​

注册模式结果码​

识别模式结果码​

核验模式结果码​

网络结果码​

安全警告​

从 v1.2 升级到 v1.4​

后续步骤与支持​

版本更新记录

简介

模块概览

功能特性

工作流程

1. 获取用户令牌

2. 启动 SDK

3. 获取回调

时序图

开发环境要求

集成步骤

SDK 软件包：请联系交付人员获取

前置条件

Android 集成

iOS 集成

Flutter 集成

API 参考

识别 (1:N) 调用示例

Params

各模式必填项

身份参数

可选参数

Result

结果码参考

通用结果码

注册模式结果码

识别模式结果码

核验模式结果码

网络结果码

安全警告

从 v1.2 升级到 v1.4

后续步骤与支持