跳到主要内容

腾讯刷掌移动端（SDK）API接口文档(v2.3.0)

移动端接口 Max 与 Standard 版本有差异，请通过下方标签页切换查看对应版本。

Tencent Palm Mobile Manager SDK 提供了一套完整的移动端掌纹生物识别解决方案，支持注册、核验和识别三种模式。它包含预构建的 UI 界面和强大的 AI 算法，旨在简化开发流程，让您的应用能轻松集成全面的掌纹生物识别能力。

核心模块​

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

管理模块​

用户管理中心，主要负责管理掌纹信息，如：注册用户流程，管理用户掌纹信息

  • 用户管理 - 自动查询/创建用户，展示手掌注册状态（已注册/未注册/预录入）
  • 业务流程 - 支持注册、识别(1:N)、核验(1:1)三种模式
  • 界面交互 - 展示操作引导、处理结果、错误提示与重试
  • 结果处理 - 接收采集结果，自动上报识别/核验记录（提示：需要在刷掌管理平台配置场景对应 SN 为 PalmMobileManager，才支持记录上报）
  • 结果回调 - 仅在关键错误（Token 失效、网关认证失败）或用户退出时回调您的应用

采集模块​

手掌信息采集，主要负责采集算法部分，如：采集掌纹、注册/核验/识别

  • 相机采集 - 唤起摄像头，提供实时预览画面
  • AI 处理 - 内置掌纹检测、质量评估、活体动作判断等算法能力
  • 交互引导 - 引导用户完成"张开手掌"、"握拳"等动作
  • 数据上报 - 将采集数据加密上传至服务器，可选上传采集视频

功能特性​

  • 多种模式：支持注册、核验和识别三种模式，覆盖全面的业务需求。
  • 跨平台支持：提供开箱即用的 Android、iOS 与 Flutter 版本SDK。
  • 优化的AI算法：在SDK内部直接集成了高性能的检测配准、活体判断、质量控制、动作判断等算法。
  • 模块化UI组件：为管理和采集模块提供了完整、预构建的UI，极大缩短了开发周期。
  • 安全设计：所有掌纹数据在传输至服务器前均经过自动加密。

核心概念​

为了更好地理解本SDK采集结果和设备端使用差异，请了解以下特征库的区别：

  • 【掌纹】单因子特征库
    • 说明: 仅记录【掌纹】单因子信息。因手机摄像头无法采集【掌静脉】，本SDK仅采集【掌纹】单因子信息。
  • 【掌纹+掌静脉】双因子特征库
    • 说明: 同时记录【掌纹】和【掌静脉】双因子信息。这是用于专业设备录入的高安全标准。

工作流程​

注意：若仅使用采集模块（则不会自动通过管理模块创建用户），请先由您的服务端调用 Tencent PalmAI Platform OpenAPI 的 CreateUser 接口完成用户创建，再执行以下步骤。

1. 获取用户令牌​

您的服务端必须首先从 Tencent PalmAI Platform OpenAPI 请求一个与用户 UserId 绑定的 AccessToken

提示：调用【获取访问凭证】接口时，需要指定 GrantType 类型为 client_credential_user，同时指定 UserId 参数。

- **管理模块**
您的应用 --[UserId]--> 您的服务端 --[调用 CreateAccessToken]--> Tencent PalmAI Platform
您的应用 <--[AccessToken]-- 您的服务端 <--[AccessToken]-- Tencent PalmAI Platform

- **采集模块**：
您的应用 --[UserId（未注册）][UserName]--> 您的服务端 --[调用 CreateUser]--> Tencent PalmAI Platform
您的应用 --[UserId（已注册）]--> 您的服务端 --[调用 CreateAccessToken]--> Tencent PalmAI Platform
您的应用 <--[AccessToken]-- 您的服务端 <--[AccessToken]-- Tencent PalmAI Platform

2. 启动 SDK​

我们的后端服务分为刷掌业务平台和刷掌算法平台两部分，SDK 提供对应的两个模块进行连接：

SDK 模块对接后端说明
管理模块刷掌业务平台提供完整的掌纹管理界面，从管理页面进入，进行页面交互后跳转至采集画面，由 SDK 内部处理 result
采集模块刷掌算法平台直接跳转摄像头采集画面，进行掌纹采集及算法处理，由您自行设计管理页面并处理 result

根据您的业务需求选择对应模块：

  • 管理模块：使用 AccessToken 和必填用户信息启动（enableManager = true）
  • 采集模块：使用 AccessToken 和必填用户信息启动（enableManager = false）

3. 自动化流程​

管理模块会自动完成以下流程，无需您的应用干预：

  1. 查询用户注册状态
  2. 展示友好的界面和操作提示
  3. 根据模式(注册/识别/核验)调用采集模块
  4. 接收并处理采集模块的各种情况(成功、权限问题、网络问题、算法结果等)
  5. 提示用户重试或展示最终结果

采集模块则需要自己处理 result 结果，其中 code 字段对应本文档中结果码

4. 获取回调​

用户点击返回或遇到关键错误时，管理模块会关闭并回调至您的应用，采集模块需要您自己处理

开发环境要求​

为确保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）。此方式可以免去申请授权证书的步骤。

Android 集成​

  1. 导入 LocalMavenRepo 仓库

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

  2. 配置 app/build.gradle 文件

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

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

  3. 简要调用示例

    PalmMobileManager.Params params = new PalmMobileManager.Params.Builder(USER_TOKEN, USER_ID, USER_NAME, USER_PHONE_NO)
        // 设置模式（可选，默认为 REGISTRATION）
        // .setMode(PalmMobileManager.Mode.VERIFICATION)
        // .setTargetUserId(TARGET_USER_ID)
        // 您也可以设置自己的 Tencent PalmAI Platform 服务器配置。
        // .setBaseUrl(BASE_URL)
        // .setAppId(APP_ID)
        // 可以自定义 HTTP 请求头来访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）
        // .addCustomHeader("Authorization", "YOUR_JWT_TOKEN")
        // 您可以选择是否上传视频
        //.setEnableVideoUpload(true)
        // 您可以选择启动管理模块或采集模块
        // - true: 启动管理模块（默认）
        // - false: 启动采集模块
        // .setEnableManager(true)
        // 您可以选择采集时使用哪只手掌 (PalmDirection.LEFT / RIGHT / UNSPECIFIED)
        // .setPalmDirection(PalmDirection.UNSPECIFIED)
        .build();

    PalmMobileManager.start(this, params, result -> {
        // TODO: 根据 result.code 处理业务逻辑
        Log.i("PalmMobileManager", result.toString());

        // 使用采集模块时, 您需要自己对 result 的结果进行分析
        // 请参考 README 中的 code 和 message 映射关系，data 中包含了 result 的详细信息
    });

  4. 参考示例工程

    详见 Android/example 工程项目

iOS 集成​

  1. 导入Framework

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

  2. 配置相机权限

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

  3. 简要调用示例

    let params = PalmMobileManagerParams(
        token: token,
        userId: userId,
        userName: userName,
        phoneNo: phoneNo,
    )
    // 设置模式（可选，默认为 registration）
    // params.mode = .verification
    // params.targetUserId = TARGET_USER_ID
    // 您也可以设置自己的 Tencent PalmAI Platform 服务器配置。
    // params.appId = APP_ID
    // params.baseUrl = BASE_URL
    // 可以自定义 HTTP 请求头来访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）
    // params.addCustomHeader(
    //     withKey: "Authorization",
    //     value: "YOUR_JWT_TOKEN"
    // )
    // 您可以选择是否上传视频
    //params.enableVideoUpload = true
    // 您可以选择启动管理模块或采集模块
    // - true: 启动管理模块（默认）
    // - false: 启动采集模块
    // params.enableManager = true
    // 您可以选择采集时使用哪只手掌 (.left / .right / .unspecified)
    // params.palmDirection = .unspecified
    PalmMobileManager.start(
        from: controller,
        params: params,
        completion: { result in
            // TODO: 根据 result.code 处理业务逻辑
            print("PalmMobileManager succeed: \(result.code): \(result.message): \(result.data)")

            // 使用采集模块时, 您需要自己对 result 的结果进行分析
            // 请参考 README 中的 code 和 message 映射关系，data 中包含了 result 的详细信息
        }
    )

  4. 参考示例工程

    详见 iOS/example 工程项目

Flutter 集成​

  1. 导入插件

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

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

  2. 添加依赖

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

    dependencies:
        flutter:
            sdk: flutter

    # ... 其他依赖
    palm_mobile_manager:
        path: packages/palm_mobile_manager
        version: 0.0.0-dev

  3. 添加 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"))
            }
        }
    }

  4. iOS配置相机权限

    在 [YOUR_FLUTTER_APP]/iOS/Runner/Info.plist 中添加 NSCameraUsageDescription

    <key>NSCameraUsageDescription</key>
    <string>需要相机权限以进行掌纹扫描。</string>

  5. 简要调用示例

    final params = Params(
      token: _tokenController.text,
      userId: _userIdController.text,
      phoneNo: _phoneNoController.text,
      userName: _userNameController.text,
      // 设置模式（可选，默认为 REGISTRATION）
      // mode: Mode.verification,
      // targetUserId: TARGET_USER_ID,
      // 您也可以设置自己的 Tencent PalmAI Platform 服务器配置。
      // appId: APP_ID, // YOUR OWN APP ID
      // baseUrl: BASE_URL,
      // 可以自定义 HTTP 请求头来访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）
      // customHeaders: {'Authorization': 'YOUR_JWT_TOKEN'},
      // 您可以选择是否上传视频
      // enableVideoUpload: true,
      // 您可以选择启动管理模块或采集模块
      // - true: 启动管理模块（默认）
      // - false: 启动采集模块
      //enableManager: true,
      // 您可以选择采集时使用哪只手掌 (PalmDirection.left / right / unspecified)
      //palmDirection: PalmDirection.unspecified,
    );

    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');
    }

  6. 参考示例工程

    详见 flutter/palm_mobile_manager/example 工程项目

  7. 首次打开示例工程的 iOS 项目（重要）

    example/ios/Pods/、example/ios/Flutter/Generated.xcconfig、.dart_tool/ 等均为 .gitignore 排除的本地产物，软件包/仓库中不会包含。直接用 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 参考​

Params​

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

提示：必填参数+可选参数在启动 SDK 传入时，仅进行非空、非法校验，否则返回 code=10001。接入方应遵循下述格式要求，否则会在管理模块提示用户网络相关错误。

必填参数​

参数类型描述
tokenString用户身份令牌，用于授权本次 SDK 操作。
userIdString用户唯一标识符。
格式要求：1-64 字符，仅支持ASCII字母（A-Z,a-z）、数字（0-9）、短横线（-）和下划线（_），不允许空格及其他空白字符。
userNameString用户名称。
格式要求：1-64 字符（Unicode字符），不允许仅由空白字符组成，Name前后不允许包含空格（允许字符中间有空格）。支持脱敏处理。
phoneNoString用户手机号。
格式要求：纯数字（手机号4-20位）、包含区号（1-3位），如 (+86)13800138000。支持脱敏处理。

可选参数​

参数类型默认值描述
modeModeREGISTRATION业务模式。可选值：
• REGISTRATION - 注册模式
• VERIFICATION - 核验模式 (1:1)
• RECOGNITION - 识别模式 (1:N)
targetUserIdString-待核验的目标用户 ID。
注意：VERIFICATION 模式下必需。
appIdint223应用 ID，由服务方提供。
baseUrlStringhttps://app.intl.palm.tencent.comAPI 服务地址。
enableVideoUploadBooleantrue是否上传采集视频。
enableManagerBooleantrue是否启动管理模块。为 true 时启动管理模块，为 false 时启动采集模块。
customHeadersMap<String, String>-自定义 HTTP 请求头。用于访问您配置的 BaseUrl 所对应的网关（如传递 JWT Token）
palmDirectionStringunspecified采集时使用哪只手掌。可选值：
• unspecified - 任意手掌均可（默认）
• left - 强制使用左手
• right - 强制使用右手

Result​

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

属性类型描述
codeint结果码，详见下方回调结果码列表。
messageString描述信息，仅用于调试。

回调结果码​

管理模块会自动处理采集模块中的大部分结果。您的应用仅会收到以下结果码的回调：

结果码场景处理建议
0操作成功或用户主动返回无需处理
10001参数非法检验参数是否合法，如必填项是否为空，BaseUrl 是否合法等
10012Token 无效或过期重新获取 Token
10401指定 BaseUrl 网关认证失败请联系 BaseUrl 提供者进行技术支持，或添加您网关对应 jwt 认证信息

完整结果码参考​

说明： 采集模块不会捕获结果码进行内部处理，完整结果码参考如下：

点击展开查看所有结果码
通用结果码​
结果码开发说明
0操作成功（会回调）
10000未知错误
10001参数无效（会回调）
10002用户取消采集操作
10003相机权限被拒绝
10004相机初始化失败
10005不支持的相机预览尺寸
10006SDK 初始化失败
10007SDK 运行时错误
10008采集超时（30 秒超时）
10012Token 无效或已过期（会回调）
10016授权证书验证失败
10017用户名格式不正确
10018用户ID格式不正确
10019电话号码格式不正确
10021用户名不存在
10022租户已禁止注册用户
10023手机号在租户下已存在
10024租户已禁止掌纹注册
注册模式结果码​
结果码开发说明
10100活体检测失败
10101质量检查失败
10102活体视频验证失败
10103该手掌已注册
10104与已有用户高度相似
识别模式结果码​
结果码说明
10200用户未识别
核验模式结果码​
结果码说明
10200待验证用户未找到特征
10300待验证用户不存在
10301待验证用户未注册掌纹
10302待验证用户未注册当前手掌方向
网络结果码​
结果码说明
10401网关未认证访问（会回调）
10500网络错误

安全警告​

生产环境安全要求​

严禁在生产环境的客户端代码中硬编码 SecretId 或 SecretKey！

这会将您的平台账户密钥暴露给所有用户，攻击者可利用这些密钥攻击您的服务，造成严重损失。

正确做法（生产环境）：

- **管理模块**
您的应用 --[UserId]--> 您的服务端 --[调用 CreateAccessToken]--> Tencent PalmAI Platform
您的应用 <--[AccessToken]-- 您的服务端 <--[AccessToken]-- Tencent PalmAI Platform

- **采集模块**：
您的应用 --[UserId（未注册）][UserName]--> 您的服务端 --[调用 CreateUser]--> Tencent PalmAI Platform
您的应用 --[UserId（已注册）]--> 您的服务端 --[调用 CreateAccessToken]--> Tencent PalmAI Platform
您的应用 <--[AccessToken]-- 您的服务端 <--[AccessToken]-- Tencent PalmAI Platform

测试环境快速启动​

仅用于本地开发/内部测试/隔离 Demo 环境，演示如何快速获取 Token

/**
 * [仅供测试] 快速获取 Token 并启动 SDK
 * 警告：生产环境中，Token 必须从后端服务器获取
 */
private void startForTesting() {
    // 初始化 OpenApiService
    OpenApiService.init(OPEN_API_URL, APP_ID, SECRET_ID, SECRET_KEY);

    CreateAccessTokenRequest req = new CreateAccessTokenRequest(USER_ID);
    OpenApiService.getInstance().createAccessToken(req, new ApiClient.Callback<CreateAccessTokenResponse>() {
        @Override
        public void onSuccess(CreateAccessTokenResponse response) {
            start(response.accessToken);  // 使用 Token 启动 SDK
        }

        @Override
        public void onFailure(int code, String message) {
            Log.e("PalmMobileManager", "Failed to get token: " + code + " - " + message);
        }
    });
}

提示：AppId/BaseUrl/SecretId/SecretKey 需匹配使用。如需测试凭证，请联系技术支持获取。

后续步骤与支持​

  • 查阅示例工程: 我们强烈建议您在集成前，先编译并运行对应平台的示例工程，这将帮助您快速了解 SDK 的完整调用流程。
  • 获取技术支持: 如果在集成过程中遇到任何问题，请联系您的技术支持代表。