Tencent Palm Mobile App SDK Reference

Audience: Android / iOS / Flutter engineers on the integrating side

This document helps you integrate palm capture into native apps. The user token required by the SDK is issued by your backend via CreateSdkUserToken. For browser / H5 integration, see Mobile (H5) SDK.

Changelog

Version	Release Date	Changes
v1.4.0	2026-10-13	Recognition (1:N) aligned with the H5 SDK v1.4.0 contract: `AppId` in `customHeaders` is required in recognition mode (missing returns `10001`); the SDK writes it into the `search_rgb_palm` body, and the palm image / liveness image / liveness video are encrypted with `AppId` (registration / verification keep `userId`). `token` and `userId` may be empty; no `Authorization` header is sent when `token` is empty. Flutter `Params` default `token` / `userId` to an empty string. Result codes add `10020` / `10302`
v1.2.0	2026-08-18	`RecognitionData.sessionId` (from `SearchRgbPalmRsp.SessionId`; temporary lookup credential, ~2h TTL, for verifying recognition results server-side)
v1.0.0	2026-07-20	Initial release

There is no separate v1.3 release for the native SDKs. Upgrading from v1.2? See "Upgrading from v1.2 to v1.4" at the end.

Introduction

The Tencent Palm Mobile Manager SDK provides a complete solution for mobile palm biometrics, supporting registration, verification (1:1) and recognition (1:N) modes. It integrates AI algorithms and camera acquisition, enabling your app to easily add palm biometric capabilities.

Overview

The SDK provides the Acquisition Module, which is responsible for on-device palm acquisition and algorithm processing:

Camera Acquisition — Launches the camera and provides a real-time preview
AI Processing — Built-in algorithms for palm detection, quality assessment, liveness action check, etc.
Interactive Guidance — Guides users through actions like "open palm" and "make fist"
Data Upload — Encrypts and uploads collected data to the server (video included when applicable)
Result Callback — Returns the acquisition result (success, failure, algorithm output) to your app; you own the subsequent UI and business logic

Features

Multiple Modes: Supports Registration, Verification (1:1) and Recognition (1:N).
Cross-Platform Support: Out-of-the-box SDKs for Android, iOS, and Flutter.
Optimized AI Algorithms: Detection and alignment, liveness, quality control, and action check are integrated directly in the SDK.
Secure by Design: All palm data is automatically encrypted before being transmitted to the server.

Workflow

1. Obtain User Token

Token issuance MUST happen on your backend server. Your server calls CreateSdkUserToken on Tencent PalmXAI Platform, passing the end user's UserId, and delivers the returned short-lived token to the client. The token is scoped to that single user and expires automatically.

Recognition (1:N) does not target a specific user and needs no token: pass empty token and userId, put AppId in customHeaders, and the SDK recognizes anonymously within that app. Registration and verification (1:1) still require a token.

2. Start the SDK

For registration / verification, start the SDK with the token and UserId; for recognition (1:N), only AppId in customHeaders is needed. The SDK jumps directly to the camera acquisition screen, performs palm collection and algorithm processing, and returns the result via callback.

3. Receive Callback

Your app receives the Result in the callback. The code field corresponds to the result codes in this document, and the data field contains the detailed acquisition payload (registration / recognition / verification).

Sequence Diagram

Development Environment Requirements

To ensure the stability and compatibility of the SDK, make sure your development environment meets the following minimum requirements:

Platform	Requirements
Android	● JDK: 17 or later ● Android Gradle Plugin (AGP): 8.5 or later ● Android Studio: Koala \| 2024.1.1 or later (to match AGP requirements) ● minSdkVersion: 24 ● compileSdkVersion / targetSdkVersion: 34+
iOS	● Xcode: 16.0 or later ● Minimum Deployment Target: iOS 13.0
Flutter	● Flutter SDK: 3.25.0 or later

Integration Steps

SDK Package: Please Contact Your Delivery Representative

The following directory structure is based on the SDK package.

Prerequisites

Authorization certificate: Provide us with your app's Android ApplicationId and iOS BundleId so that we can generate and bind the authorization certificate required by the SDK's algorithm runtime.

Note: For demo development. If you are only developing and testing, you can set your app's ID to match the com.tencent.palm.* wildcard (e.g., com.tencent.palm.demo). This lets you skip the certificate application step.
User & Token (registration / verification): the end user is provisioned on the platform; your backend issues the token via CreateSdkUserToken.
App ID (recognition (1:N)): your app id (AppId) on PalmXAI Platform, passed via customHeaders.
Privacy consent: the SDK does not show a privacy agreement or record user consent. Obtain explicit user consent in your app before calling PalmMobileManager.start.

Android Integration

Import the LocalMavenRepo

Copy Android/repo into your project, e.g. [YOUR_PROJECT]/app/repo.

Configure app/build.gradle

// ...
repositories {
    // ... other repositories
    maven {
        name = "LocalMavenRepo"
        url = uri("${projectDir}/repo") // make sure the path is correct
    }
}

dependencies {
    // ... other dependencies
    implementation "com.tencent.palm:PalmMobileManager:1.4.0"
}

Minimal example

PalmMobileManager.Params params = new PalmMobileManager.Params.Builder(
        USER_TOKEN,
        USER_ID)
    // Set mode (optional, defaults to REGISTRATION)
    // .setMode(PalmMobileManager.Mode.VERIFICATION)
    // Recognition (1:N): empty token / userId, AppId required (see "Recognition (1:N) Example")
    // .setMode(PalmMobileManager.Mode.RECOGNITION)
    // .addCustomHeader("AppId", APP_ID)
    // Constrain palm direction (optional, defaults to INVALID = auto-detect)
    // .setPalmDirection(PalmDirection.LEFT)
    // You can also point the SDK at your own Tencent PalmXAI Platform deployment.
    // .setBaseUrl(BASE_URL)
    // Custom HTTP headers for the gateway behind your BaseUrl (e.g. a JWT token).
    // Note: Authorization overrides the "Bearer <token>" the SDK builds from token. Use it only when
    // your self-hosted gateway authenticates and forwards the user token to Tencent PalmXAI Platform
    // .addCustomHeader("Authorization", "YOUR_JWT_TOKEN")
    .build();

PalmMobileManager.start(this, params, result -> {
    // TODO: analyze the result and drive your business logic
    // See the result code mapping below; data contains the details
    Log.i("PalmMobileManager", result.toString());
});

Example project

See the Android/example project in the SDK package.

iOS Integration

Import the Framework

Drag iOS/Frameworks/PalmMobileManager.xcframework into your Xcode project and set it to "Embed & Sign" under "General" → "Frameworks, Libraries, and Embedded Content".
Configure camera permission

Add Privacy - Camera Usage Description to Info.plist with a user-facing description.

Minimal example

let params = PalmMobileManagerParams(
    token: token,
    userId: userId
)
// Set mode (optional, defaults to registration)
// params.mode = .verification
// Recognition (1:N): empty token / userId, AppId required (see "Recognition (1:N) Example")
// params.mode = .recognition
// params.addCustomHeader(withKey: "AppId", value: appId)
// Constrain palm direction (optional, defaults to .invalid = auto-detect)
// params.palmDirection = .left
// You can also point the SDK at your own Tencent PalmXAI Platform deployment.
// params.baseUrl = BASE_URL
// Custom HTTP headers for the gateway behind your BaseUrl (e.g. a JWT token).
// Note: Authorization overrides the "Bearer <token>" the SDK builds from token. Use it only when
// your self-hosted gateway authenticates and forwards the user token to Tencent PalmXAI Platform
// params.addCustomHeader(
//     withKey: "Authorization",
//     value: "YOUR_JWT_TOKEN"
// )
PalmMobileManager.start(
    from: controller,
    params: params,
    completion: { result in
        // TODO: analyze the result and drive your business logic
        // See the result code mapping below; data contains the details
        print("PalmMobileManager: \(result.code): \(result.message): \(String(describing: result.data))")
    }
)

Example project

See the iOS/example project in the SDK package.

Flutter Integration

Import the plugin

Place flutter/palm_mobile_manager under your project's packages directory (create it if missing).

[YOUR_FLUTTER_APP]/
├── packages/
│   └── palm_mobile_manager/  <-- plugin directory
├── lib/
...
└── pubspec.yaml

Add the dependency

Add a local path dependency in [YOUR_FLUTTER_APP]/pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter

  # ... other dependencies
  palm_mobile_manager:
    path: packages/palm_mobile_manager

Add the Android LocalMavenRepo path

Add the Maven repository in [YOUR_FLUTTER_APP]/android/build.gradle.kts (or build.gradle):

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

iOS camera permission

Add NSCameraUsageDescription to [YOUR_FLUTTER_APP]/ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for palm scanning.</string>

Minimal example

final params = Params(
  token: _tokenController.text,
  userId: _userIdController.text,
  // Set mode (optional, defaults to Mode.registration)
  // mode: Mode.verification,
  // Recognition (1:N): token / userId may be omitted, AppId required (see "Recognition (1:N) Example")
  // mode: Mode.recognition,
  // Constrain palm direction (optional, defaults to PalmDirection.invalid = auto-detect)
  // palmDirection: PalmDirection.left,
  // You can also point the SDK at your own Tencent PalmXAI Platform deployment.
  // baseUrl: BASE_URL,
  // Custom headers: put all keys in one Map and keep what you need
  // customHeaders: {
  //   // App id: required for recognition (1:N); used inside the SDK, not sent as a header
  //   'AppId': appId,
  //   // For the gateway behind your BaseUrl (e.g. a JWT token). Overrides the "Bearer <token>" the SDK
  //   // builds from token; only for self-hosted gateways that forward the user 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');
}

Example project

See the flutter/palm_mobile_manager/example project in the SDK package.
Opening the example iOS project for the first time (important)

example/ios/Pods/, example/ios/Flutter/Generated.xcconfig, .dart_tool/, etc. are locally generated and not included in the package. Opening example/ios/Runner.xcworkspace directly in Xcode reports:
```
Unable to load contents of file list:
'/Target Support Files/Pods-Runner/Pods-Runner-frameworks-Release-input-files.xcfilelist'
```
This is standard for Flutter plugin projects (unrelated to the SDK version). Run the following three steps in flutter/palm_mobile_manager/ first (pod install depends on the Generated.xcconfig produced by the previous step, so keep the order):
```
flutter pub get                       # plugin dependencies
(cd example && flutter pub get)       # generates example .symlinks and ios/Flutter/Generated.xcconfig
(cd example/ios && pod install)       # generates Pods and xcfilelist
```
Then open example/ios/Runner.xcworkspace in Xcode and build.

If pod install reports Unable to find a specification for ..., your local CocoaPods spec repo is behind Podfile.lock; retry with pod install --repo-update.

API Reference

Recognition (1:N) Example

Recognition does not target a specific user: pass empty token and userId; AppId must be provided in customHeaders, otherwise 10001 is returned immediately. On success, RecognitionData returns the matched user's userId, score and 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},
);

If a token is also passed, it must belong to the same app as AppId; otherwise 10012 is returned.

Params

Configuration object for starting the SDK.

Note: Only non-empty and validity checks are performed at startup (token / userId for registration / verification; AppId in customHeaders for recognition); failure returns code=10001. Follow the format requirements below; otherwise network-related errors will occur at runtime.

Required Fields by Mode

Parameter	Registration	Verification (1:1)	Recognition (1:N)
`token`	✅	✅	may be empty
`userId`	✅ user to enroll	✅ compare target	may be empty
`AppId` in `customHeaders`	optional	optional	✅

Identity Parameters

Parameter	Type	Description
`token`	`String`	User identity token for authorizing this SDK operation (issued by your backend via `CreateSdkUserToken`). May be an empty string for `RECOGNITION` (anonymous recognition keyed by `AppId` in `customHeaders`); no `Authorization` header is sent when empty.
`userId`	`String`	Unique identifier of the target user. • `REGISTRATION`: the user whose palm is being enrolled • `VERIFICATION`: the registered user to compare against (1:1) • `RECOGNITION`: may be an empty string (1:N does not target a specific user) Format: 1-64 characters. Only ASCII letters (A-Z, a-z), digits (0-9), hyphens (-), and underscores (_). No spaces or whitespace.

Optional Parameters

Parameter	Type	Default	Description
`mode`	`Mode`	`REGISTRATION`	Business mode. Options: • `REGISTRATION` - Registration • `VERIFICATION` - Verification (1:1) • `RECOGNITION` - Recognition (1:N)
`baseUrl`	`String`	`https://open.intl.palm.tencent.com`	API service address.
`customHeaders`	`Map<String, String>`	-	Custom HTTP headers for the gateway behind your configured `BaseUrl` (e.g., a JWT token). `AppId` (case-insensitive key, trimmed) is the app id and is not sent as a header: • required for `RECOGNITION`; missing returns `10001`. When `token` is provided it must belong to the same app. The SDK writes it into the `search_rgb_palm` body and uses it as the palm image / video encryption factor • other modes use it for diagnostic log reporting Note: keys other than `AppId` are sent as-is, and `Authorization` overrides the `Bearer <token>` the SDK builds from `token`. Pass it only when your self-hosted gateway authenticates the request and forwards the user token to Tencent PalmXAI Platform; never when calling the platform directly.
`palmDirection`	`PalmDirection`	`INVALID`	Constrain acquisition to a specific hand. Options: • `INVALID` - Auto-detect left or right (default) • `LEFT` - Left hand only • `RIGHT` - Right hand only

Result

Result object returned via callback when the SDK exits. Parse it yourself: code maps to the result codes below, and data contains the details.

Property	Type	Description
`code`	`int`	Result code. See the reference below.
`message`	`String`	Descriptive message for debugging only.
`data`	`Data?`	Payload for the current mode: `RegistrationData` / `RecognitionData` / `VerificationData`; `null` on non-success. On recognition success, `RecognitionData.sessionId` is a temporary lookup credential (~2h TTL); hand it to your server to verify the result via GetSessionResult.

Result Code Reference

Common Result Codes

Code	Developer Notes
0	Operation successful
10000	Unknown error
10001	Invalid parameters (e.g. `AppId` missing in recognition mode)
10002	User cancelled acquisition
10003	Camera permission denied
10004	Camera initialization failed
10005	Unsupported camera preview size
10006	SDK initialization failed
10007	SDK runtime error
10008	Acquisition timeout (30 seconds)
10012	Invalid or expired token; in recognition, token and `AppId` belong to different apps
10016	Authorization certificate validation failed
10018	Invalid UserId format
10020	App has been disabled
10021	User does not exist

Registration Mode Result Codes

Code	Developer Notes
10100	Liveness detection failed
10101	Quality check failed
10102	Liveness video verification failed
10103	Palm already registered
10104	High similarity with existing user

Recognition Mode Result Codes

Code	Description
10200	No registered palm recognized (1:N no match)

Verification Mode Result Codes

Code	Description
10200	No palm feature of the target user found in the compare library (shared with recognition)
10300	Target user not found
10301	Target user has not registered a palm
10302	Target user has not registered the current palm direction

Network Result Codes

Code	Description
10401	Unauthorized gateway access
10500	Network error

Security Warning

Never embed your Tencent PalmXAI Platform api_key in client code. Token issuance (CreateSdkUserToken) must be performed by your backend; only the returned short-lived per-user token is delivered to the client.

The AppId passed for recognition (1:N) is an app identifier, not a secret, and may live in the client. Hand the sessionId returned on a successful recognition to your server to verify the result — do not trust the userId in the client callback alone.

Upgrading from v1.2 to v1.4

v1.4 changes are concentrated in recognition (1:N). Integrations that only use registration and verification (1:1) can upgrade without code changes.

#	Change	Impact	Code change needed
1	Recognition (1:N) requires `AppId` in `customHeaders`	Breaking: returns `10001` immediately if missing	✅ Required if you use recognition
2	Recognition palm images and video are encrypted with `AppId`	Handled inside the SDK; backend decrypts by the `AppId` in the body	❌ As long as the correct `AppId` is passed
3	Recognition no longer needs `token`; `userId` is optional	Optional: no need to issue tokens for recognition	Recommended

Recognition call diffs:

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},
 )

Upgrade checklist:

Replace with the v1.4.0 SDK package (Android aar / iOS xcframework / Flutter plugin)
Every RECOGNITION call passes AppId in customHeaders
AppId matches the current environment (test / production)
(Optional) Remove logic that issues a token or fills a placeholder userId for recognition
Verify recognition results on your server with sessionId
Regression-test registration, verification, and recognition

FAQ:

Symptom	Likely cause	Fix
Recognition returns `10001` right after start	`AppId` missing or empty	Pass `AppId`
Recognition returns `10012`	`AppId` does not exist in this environment (e.g. a test ID used in production); or a token was passed but is invalid or belongs to another app	Check `AppId` and environment; you may omit the token for recognition
Recognition keeps returning `10200` (not recognized)	`AppId` belongs to a different app whose library does not contain the user's palm	Use the same `AppId` as during registration
Registration / verification returns `10001`	These modes still require non-empty `token` and `userId`	Pass them as before

Next Steps & Support

Review the example projects: We strongly recommend building and running the example project for your platform before integrating, to understand the complete SDK flow.
Server APIs: token issuance, palm query / deletion, and recognition result verification — see the KYC Open API Integration Guide.
H5 (Web) integration: see Mobile (H5) SDK.
Support: contact your technical support representative.

Changelog​

Introduction​

Overview​

Features​

Workflow​

1. Obtain User Token​

2. Start the SDK​

3. Receive Callback​

Sequence Diagram​

Development Environment Requirements​

Integration Steps​

SDK Package: Please Contact Your Delivery Representative​

Prerequisites​

Android Integration​

iOS Integration​

Flutter Integration​

API Reference​

Recognition (1:N) Example​

Params​

Required Fields by Mode​

Identity Parameters​

Optional Parameters​

Result​

Result Code Reference​

Common Result Codes​

Registration Mode Result Codes​

Recognition Mode Result Codes​

Verification Mode Result Codes​

Network Result Codes​

Security Warning​

Upgrading from v1.2 to v1.4​

Next Steps & Support​

Changelog

Introduction

Overview

Features

Workflow

1. Obtain User Token

2. Start the SDK

3. Receive Callback

Sequence Diagram

Development Environment Requirements

Integration Steps

SDK Package: Please Contact Your Delivery Representative

Prerequisites

Android Integration

iOS Integration

Flutter Integration

API Reference

Recognition (1:N) Example

Params

Required Fields by Mode

Identity Parameters

Optional Parameters

Result

Result Code Reference

Common Result Codes

Registration Mode Result Codes

Recognition Mode Result Codes

Verification Mode Result Codes

Network Result Codes

Security Warning

Upgrading from v1.2 to v1.4

Next Steps & Support