Skip to main content

Tencent Palm Mobile-Side (SDK) API Documentation (v2.3.0)

The mobile interfaces differ between the Max and Standard versions. Use the tabs below to switch and view the corresponding version.

The Tencent Palm Mobile Manager SDK provides a complete mobile palmprint biometric identification solution, supporting three modes: Registration, Verification, and Recognition. It bundles prebuilt UI screens and powerful AI algorithms to simplify development and allow your application to easily integrate comprehensive palmprint biometric capabilities.

Core Modules​

The SDK consists of two core modules: the Manager Module and the Capture Module.

Manager Module​

User Management Center, primarily responsible for managing palmprint information, such as: user enrollment flow and management of user palmprint information.

  • User Management - Automatically queries/creates users and displays palm enrollment status (Enrolled / Not Enrolled / Pre-enrolled).
  • Business Flow - Supports three modes: Registration, Recognition (1:N), and Verification (1:1).
  • UI Interactions - Displays operation guidance, result handling, error prompts, and retries.
  • Result Handling - Receives the capture result and automatically reports the recognition/verification record. (Note: The corresponding scene SN must be configured as PalmMobileManager on the Palm management platform for record reporting to be supported.)
  • Result Callback - Only calls back to your application on critical errors (Token invalid, gateway authentication failed) or when the user exits.

Capture Module​

Palm information capture, primarily responsible for the algorithm portion, such as: palmprint capture and registration/verification/recognition.

  • Camera Capture - Launches the camera and provides a real-time preview.
  • AI Processing - Built-in algorithms for palm detection, quality assessment, and liveness action judgment.
  • Interactive Guidance - Guides the user through actions such as "open your palm" and "make a fist".
  • Data Reporting - Encrypts captured data and uploads it to the server; optionally uploads the capture video.

Features​

  • Multiple modes: Supports Registration, Verification, and Recognition modes, covering a full range of business needs.
  • Cross-platform: Provides out-of-the-box SDKs for Android, iOS, and Flutter.
  • Optimized AI algorithms: The SDK directly integrates high-performance detection & alignment, liveness judgment, quality control, and action-judgment algorithms.
  • Modular UI components: Provides complete prebuilt UIs for the manager and capture modules, greatly shortening the development cycle.
  • Security-by-design: All palmprint data is automatically encrypted before being transmitted to the server.

Core Concepts​

To better understand the difference between this SDK's capture results and device-side usage, please review the differences between the feature libraries below:

  • Single-factor (Palm print) feature library
    • Description: Records only single-factor palm print information. Because a phone camera cannot capture the palm vein, this SDK only captures single-factor palm print information.
  • Bimodal (Palm print + Palm vein) feature library
    • Description: Records both palm print and palm vein information. This is the high-security standard used for enrollment on professional devices.

Workflow​

Note: If you only use the Capture Module (in which case the user will not be created automatically by the Manager Module), your server must first call the CreateUser API of the Tencent PalmAI Platform OpenAPI to create the user, and then proceed with the following steps.

1. Obtain a User Token​

Your server must first request an AccessToken bound to the user's UserId from the Tencent PalmAI Platform OpenAPI.

Tip: When calling the [Obtain Access Credentials] API, specify the GrantType as client_credential_user and provide the UserId parameter.

- **Manager Module**
Your app --[UserId]--> Your server --[call CreateAccessToken]--> Tencent PalmAI Platform
Your app <--[AccessToken]-- Your server <--[AccessToken]-- Tencent PalmAI Platform

- **Capture Module**:
Your app --[UserId (not registered)][UserName]--> Your server --[call CreateUser]--> Tencent PalmAI Platform
Your app --[UserId (already registered)]--> Your server --[call CreateAccessToken]--> Tencent PalmAI Platform
Your app <--[AccessToken]-- Your server <--[AccessToken]-- Tencent PalmAI Platform

2. Launch the SDK​

Our backend service is split into two parts: the Palm Application Platform and the Palm Algorithm Platform. The SDK provides two corresponding modules to connect to them:

SDK ModuleBackendDescription
Manager ModulePalm Application PlatformProvides the complete palmprint management UI. Entered from the management page; after page interactions, the SDK transitions to the capture screen and handles the result internally.
Capture ModulePalm Algorithm PlatformJumps directly to the camera capture screen for palmprint capture and algorithm processing. You design your own management pages and handle the result.

Choose the corresponding module based on your business needs:

  • Manager Module: launched with AccessToken and the required user information (enableManager = true).
  • Capture Module: launched with AccessToken and the required user information (enableManager = false).

3. Automated Flow​

The Manager Module automatically completes the following flow, without any intervention from your application:

  1. Query the user's enrollment status.
  2. Display a user-friendly UI and operation prompts.
  3. Invoke the Capture Module based on the mode (Registration / Recognition / Verification).
  4. Receive and handle various outcomes from the Capture Module (success, permission issues, network issues, algorithm results, etc.).
  5. Prompt the user to retry or display the final result.

The Capture Module requires you to handle the result yourself; the code field corresponds to the result codes listed in this document.

4. Receive the Callback​

When the user taps back or encounters a critical error, the Manager Module closes and calls back to your application. The Capture Module requires you to handle this yourself.

Development Environment Requirements​

To ensure the SDK runs stably and is compatible with your environment, please ensure your development environment meets the following minimum requirements:

PlatformRequirements
Android● JDK: 17 or later
● Android Gradle Plugin (AGP): 8.5 or later
● Android Studio: Koala | 2024.1.1 or later (to match the AGP requirement)
● 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: contact the delivery team to obtain it​

The directory structures below are all based on the software package directory structure.

Prerequisite: Obtain the Authorization Certificate​

You need to provide us with your application's Android ApplicationId and iOS BundleId so that we can generate and bind the authorization certificate required at runtime by this SDK's algorithms.

Tip: For Demo development. If you are only developing and testing, you may set your application ID to match the wildcard com.tencent.palm.* (for example, com.tencent.palm.demo). Doing so lets you skip the authorization certificate application step.

Android Integration​

  1. Import the LocalMavenRepo repository

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

  2. Configure the app/build.gradle file

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

    dependencies {
        // ... other dependencies
        implementation "com.tencent.palm:PalmMobileManager:0.0.0-dev"
    }

  3. Brief invocation example

    PalmMobileManager.Params params = new PalmMobileManager.Params.Builder(USER_TOKEN, USER_ID, USER_NAME, USER_PHONE_NO)
        // Set the mode (optional; default is REGISTRATION)
        // .setMode(PalmMobileManager.Mode.VERIFICATION)
        // .setTargetUserId(TARGET_USER_ID)
        // You can also set your own Tencent PalmAI Platform server configuration.
        // .setBaseUrl(BASE_URL)
        // .setAppId(APP_ID)
        // You can customize HTTP request headers to access the gateway corresponding to your configured BaseUrl (e.g., pass a JWT Token)
        // .addCustomHeader("Authorization", "YOUR_JWT_TOKEN")
        // You can choose whether to upload the video
        //.setEnableVideoUpload(true)
        // You can choose to launch the Manager Module or the Capture Module
        // - true: launch the Manager Module (default)
        // - false: launch the Capture Module
        // .setEnableManager(true)
        // You can choose which palm to use during capture (PalmDirection.LEFT / RIGHT / UNSPECIFIED)
        // .setPalmDirection(PalmDirection.UNSPECIFIED)
        .build();

    PalmMobileManager.start(this, params, result -> {
        // TODO: handle the business logic according to result.code
        Log.i("PalmMobileManager", result.toString());

        // When using the Capture Module, you need to analyze the result yourself.
        // Refer to the code and message mapping in the README; data contains the detailed information of result.
    });

  4. Reference example project

    See the Android/example project.

iOS Integration​

  1. Import the framework

    Drag iOS/Frameworks/PalmMobileManager.xcframework into your Xcode project, and make sure it is set to "Embed & Sign" under "General" -> "Frameworks, Libraries, and Embedded Content".

  2. Configure camera permission

    In the Info.plist file, add Privacy - Camera Usage Description and fill in a user-visible description.

  3. Brief invocation example

    let params = PalmMobileManagerParams(
        token: token,
        userId: userId,
        userName: userName,
        phoneNo: phoneNo,
    )
    // Set the mode (optional; default is registration)
    // params.mode = .verification
    // params.targetUserId = TARGET_USER_ID
    // You can also set your own Tencent PalmAI Platform server configuration.
    // params.appId = APP_ID
    // params.baseUrl = BASE_URL
    // You can customize HTTP request headers to access the gateway corresponding to your configured BaseUrl (e.g., pass a JWT Token)
    // params.addCustomHeader(
    //     withKey: "Authorization",
    //     value: "YOUR_JWT_TOKEN"
    // )
    // You can choose whether to upload the video
    //params.enableVideoUpload = true
    // You can choose to launch the Manager Module or the Capture Module
    // - true: launch the Manager Module (default)
    // - false: launch the Capture Module
    // params.enableManager = true
    // You can choose which palm to use during capture (.left / .right / .unspecified)
    // params.palmDirection = .unspecified
    PalmMobileManager.start(
        from: controller,
        params: params,
        completion: { result in
            // TODO: handle the business logic according to result.code
            print("PalmMobileManager succeed: \(result.code): \(result.message): \(result.data)")

            // When using the Capture Module, you need to analyze the result yourself.
            // Refer to the code and message mapping in the README; data contains the detailed information of result.
        }
    )

  4. Reference example project

    See the iOS/example project.

Flutter Integration​

  1. Import the plugin

    Place flutter/palm_mobile_manager in the packages directory of your project (create it if it does not exist).

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

  2. 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
        version: 0.0.0-dev

  3. Add the Android LocalMavenRepo path

    Add the Maven repository path 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"))
            }
        }
    }

  4. Configure iOS camera permission

    Add NSCameraUsageDescription in [YOUR_FLUTTER_APP]/iOS/Runner/Info.plist:

    <key>NSCameraUsageDescription</key>
    <string>Camera permission is required to perform palmprint scanning.</string>

  5. Brief invocation example

    final params = Params(
      token: _tokenController.text,
      userId: _userIdController.text,
      phoneNo: _phoneNoController.text,
      userName: _userNameController.text,
      // Set the mode (optional; default is REGISTRATION)
      // mode: Mode.verification,
      // targetUserId: TARGET_USER_ID,
      // You can also set your own Tencent PalmAI Platform server configuration.
      // appId: APP_ID, // YOUR OWN APP ID
      // baseUrl: BASE_URL,
      // You can customize HTTP request headers to access the gateway corresponding to your configured BaseUrl (e.g., pass a JWT Token)
      // customHeaders: {'Authorization': 'YOUR_JWT_TOKEN'},
      // You can choose whether to upload the video
      // enableVideoUpload: true,
      // You can choose to launch the Manager Module or the Capture Module
      // - true: launch the Manager Module (default)
      // - false: launch the Capture Module
      //enableManager: true,
      // You can choose which palm to use during capture (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. Reference example project

    See the flutter/palm_mobile_manager/example project.

  7. Opening the example project's iOS project for the first time (important)

    example/ios/Pods/, example/ios/Flutter/Generated.xcconfig, .dart_tool/, and similar files are local build artifacts excluded by .gitignore and are not included in the SDK package or repository. Opening example/ios/Runner.xcworkspace directly in Xcode will produce:

    Unable to load contents of file list:
    '/Target Support Files/Pods-Runner/Pods-Runner-frameworks-Release-input-files.xcfilelist'

    This is standard behavior for a Flutter plugin project (unrelated to the SDK version). Please run the following three steps in order under the flutter/palm_mobile_manager/ directory (pod install depends on the Generated.xcconfig produced by the previous step; the order must not be reversed):

    flutter pub get                       # dependencies of the plugin itself
    (cd example && flutter pub get)       # generate .symlinks and ios/Flutter/Generated.xcconfig for example
    (cd example/ios && pod install)       # generate Pods and xcfilelist

    After that, open example/ios/Runner.xcworkspace in Xcode and it will compile normally.

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

API Reference​

Params​

The configuration parameter object used when launching the SDK.

Tip: When required and optional parameters are passed in at SDK launch, only null and validity checks are performed; otherwise, code=10001 is returned. The integrator should follow the format requirements below; otherwise, network-related errors will be shown to the user in the Manager Module.

Required Parameters​

ParameterTypeDescription
tokenStringUser identity token, used to authorize this SDK operation.
userIdStringUnique user identifier.
Format requirements: 1-64 characters; only ASCII letters (A-Z, a-z), digits (0-9), hyphens (-), and underscores (_) are supported. Spaces and other whitespace characters are not allowed.
userNameStringUser name.
Format requirements: 1-64 characters (Unicode). Cannot consist only of whitespace. Leading and trailing spaces are not allowed in the Name (spaces are allowed between characters). Supports data masking.
phoneNoStringUser phone number.
Format requirements: digits only (4-20 digits for the phone number) with a country code (1-3 digits), e.g., (+86)13800138000. Supports data masking.

Optional Parameters​

ParameterTypeDefaultDescription
modeModeREGISTRATIONBusiness mode. Available values:
• REGISTRATION - Registration mode
• VERIFICATION - Verification mode (1:1)
• RECOGNITION - Recognition mode (1:N)
targetUserIdString-The ID of the target user to be verified.
Note: Required in VERIFICATION mode.
appIdint223Application ID, provided by the service provider.
baseUrlStringhttps://app.intl.palm.tencent.comAPI service address.
enableVideoUploadBooleantrueWhether to upload the capture video.
enableManagerBooleantrueWhether to launch the Manager Module. true launches the Manager Module; false launches the Capture Module.
customHeadersMap<String, String>-Custom HTTP request headers. Used to access the gateway corresponding to your configured BaseUrl (e.g., pass a JWT Token).
palmDirectionStringunspecifiedWhich palm to use during capture. Available values:
• unspecified - Either palm is acceptable (default)
• left - Force use of the left hand
• right - Force use of the right hand

Result​

The result object returned via the callback when the SDK exits.

PropertyTypeDescription
codeintResult code. See the callback result code list below.
messageStringDescription; for debugging use only.

Callback Result Codes​

The Manager Module automatically handles most result codes from the Capture Module. Your application only receives callbacks for the following result codes:

Result CodeScenarioRecommendation
0Operation succeeded or user actively returnedNo action required.
10001Invalid parametersVerify that the parameters are valid, e.g., whether required fields are empty and whether the BaseUrl is valid.
10012Token invalid or expiredObtain a new Token.
10401Gateway authentication failed for the specified BaseUrlContact the BaseUrl provider for technical support, or add the JWT authentication information corresponding to your gateway.

Full Result Code Reference​

Note: The Capture Module does not intercept and handle result codes internally. The full result code reference is as follows:

Click to expand and view all result codes
Common Result Codes​
Result CodeDeveloper Description
0Operation succeeded (callback will be triggered)
10000Unknown error
10001Invalid parameter (callback will be triggered)
10002User cancelled the capture operation
10003Camera permission denied
10004Camera initialization failed
10005Unsupported camera preview size
10006SDK initialization failed
10007SDK runtime error
10008Capture timed out (30-second timeout)
10012Token invalid or expired (callback will be triggered)
10016Authorization certificate verification failed
10017Invalid user name format
10018Invalid user ID format
10019Invalid phone number format
10021User name does not exist
10022The tenant has disabled user registration
10023The phone number already exists under this tenant
10024The tenant has disabled palmprint registration
Registration Mode Result Codes​
Result CodeDeveloper Description
10100Liveness check failed
10101Quality check failed
10102Liveness video verification failed
10103The palm is already registered
10104High similarity to an existing user
Recognition Mode Result Codes​
Result CodeDescription
10200User not recognized
Verification Mode Result Codes​
Result CodeDescription
10200No feature found for the user to be verified
10300The user to be verified does not exist
10301The user to be verified has no palmprint registered
10302The user to be verified has not registered the current palm direction
Network Result Codes​
Result CodeDescription
10401Gateway unauthenticated access (callback will be triggered)
10500Network error

Security Warning​

Production Environment Security Requirements​

Do NOT hardcode SecretId or SecretKey in client code in a production environment!

Doing so exposes your platform account keys to all users. Attackers can use these keys to attack your service, causing severe losses.

Correct approach (production):

- **Manager Module**
Your app --[UserId]--> Your server --[call CreateAccessToken]--> Tencent PalmAI Platform
Your app <--[AccessToken]-- Your server <--[AccessToken]-- Tencent PalmAI Platform

- **Capture Module**:
Your app --[UserId (not registered)][UserName]--> Your server --[call CreateUser]--> Tencent PalmAI Platform
Your app --[UserId (already registered)]--> Your server --[call CreateAccessToken]--> Tencent PalmAI Platform
Your app <--[AccessToken]-- Your server <--[AccessToken]-- Tencent PalmAI Platform

Test Environment Quick Start​

Only for local development / internal testing / isolated demo environments; illustrates how to quickly obtain a Token.

/**
 * [For testing only] Quickly obtain a Token and launch the SDK
 * Warning: In production, the Token must be obtained from your backend server.
 */
private void startForTesting() {
    // Initialize 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);  // Launch the SDK with the Token
        }

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

Tip: AppId/BaseUrl/SecretId/SecretKey must be used in matching pairs. To obtain test credentials, please contact technical support.

Next Steps and Support​

  • Review the example projects: We strongly recommend that you compile and run the corresponding platform's example project before integration; this will help you quickly understand the SDK's complete invocation flow.
  • Obtain technical support: If you encounter any issues during integration, please contact your technical support representative.