Skip to main content

Tencent PalmAI Mobile App SDK Reference

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

Version Update History​

VersionRelease DateUpdate Description
v2.4.02026-08-13None
v2.2.02026-05-21Added the palmDirection parameter to specify which palm is used during capture.
v1.8.02026-03-02Added the enableManager parameter to choose whether to launch the management module or the capture module.

Introduction​

The Tencent PalmAI Mobile App SDK provides a complete mobile palm biometric solution, supporting registration, verification, and recognition modes. It includes pre-built UI interfaces and powerful AI algorithms designed to streamline development, enabling your app to easily integrate comprehensive palm biometric capabilities.

Core Modules​

The SDK consists of two core modules: Management Module and Acquisition Module.

Management Module​

User Management Center, responsible for managing palm print information, such as: user registration flow, managing user palm print information.

  • User Management - Automatically query/create users, display palm registration status (Registered/Not Registered/Pre-registered)
  • Business Flow - Support three modes: Registration, Recognition (1:N), and Verification (1:1)
  • UI Interaction - Display operation guidance, processing results, error prompts, and retry options
  • Result Processing - Receive acquisition results, automatically report recognition/verification records (Note: You need to configure the scene's SN as PalmMobileManager in the PalmAI Admin Web to support record reporting)
  • Result Callback - Only callback to your app on critical errors (Token invalid, gateway authentication failed) or user exit

Acquisition Module​

Palm Information Acquisition, responsible for the acquisition and algorithm part, such as: palm print collection, registration/verification/recognition.

  • Camera Acquisition - Launch camera and provide real-time preview
  • AI Processing - Built-in algorithms for palm print detection, quality assessment, liveness action recognition, etc.
  • Interactive Guidance - Guide users to complete actions like "open palm" and "make fist"
  • Data Upload - Encrypt and upload collected data to the server, with optional video upload

Features​

  • Multiple Modes: Supports Registration, Verification, and Recognition to cover a full range of business needs.
  • Cross-Platform Support: Provides out-of-the-box SDKs for Android, iOS, and Flutter.
  • Optimized AI Algorithms: Integrates high-performance algorithms for detection and alignment, liveness verification, quality control, and action recognition directly within the SDK.
  • Modular UI Components: Offers complete, pre-built UI for both the management and acquisition modules, significantly reducing development time.
  • Secure by Design: All palm print data is automatically encrypted before being transmitted to the server.

Core Concepts​

To better understand the acquisition results of this SDK and the differences in on-device usage, please be aware of the distinction between the following feature sets:

  • [Palm Print] Single-Factor Feature Set
    • Description: Records only palm print single-factor information. Since mobile phone cameras cannot capture palm vein data, this SDK only collects palm print single-factor information.
  • [Palm Print + Palm Vein] Dual-Factor Feature Set
    • Description: Records both palm print and palm vein dual-factor information. This is a high-security standard used for enrollment with professional devices.

Workflow​

Note: If you only use the Acquisition Module (users will not be automatically created via the Management Module), please have your server call the CreateUser API from Tencent PalmAI Platform OpenAPI to create users first, then proceed with the following steps.

1. Obtain User Token​

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

Note: When calling the [CreateAccessToken] API, you need to specify the GrantType as client_credential_user and provide the UserId parameter.

Management Module

Acquisition Module

2. Start the SDK​

Our backend services are divided into two parts: Palm Application Platform and Palm Algorithm Platform. The SDK provides two corresponding modules for connection:

SDK ModuleBackendDescription
Management ModulePalm Application PlatformProvides complete palm management UI. Enters from management page, interacts with UI, then jumps to acquisition screen. Result is handled internally by SDK.
Acquisition ModulePalm Algorithm PlatformDirectly jumps to camera acquisition screen for palm collection and algorithm processing. You design the management page and handle the result yourself.

Choose the corresponding module based on your business needs:

  • Management Module: Start with AccessToken and required user information (enableManager = true)
  • Acquisition Module: Start with AccessToken and required user information (enableManager = false)

3. Automated Flow​

Management Module automatically completes the following flow without your app's intervention:

  1. Query user registration status
  2. Display friendly UI and operation prompts
  3. Invoke the Acquisition Module based on mode (Registration/Recognition/Verification)
  4. Receive and process various situations from the Acquisition Module (success, permission issues, network issues, algorithm results, etc.)
  5. Prompt user to retry or display final results

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

4. Receive Callback​

When the user clicks back or encounters a critical error, Management Module closes and callbacks to your app. Acquisition Module requires you to handle it yourself.

Development Environment Requirements​

To ensure the stability and compatibility of the SDK, please make sure 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 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 directory structure.

Prerequisite: Obtain Authorization Certificate​

You need to provide us with your app's Android ApplicationId and iOS BundleId so that we can generate and bind the authorization certificate required for the SDK's algorithm runtime.

Note: For Demo Development. If you are only developing and testing, you can set your app's ID to a format that matches the com.tencent.palm.* wildcard (e.g., com.tencent.palm.demo). This allows you to skip the authorization certificate application step.

Android Integration​

  1. Import the LocalMavenRepo Repository

    Copy the Android/repo directory into your project, for example, to [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 Usage Example

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

    PalmMobileManager.start(this, params, result -> {
        // TODO: Handle business logic based on result.code
        Log.i("PalmMobileManager", result.toString());

        // When using the Acquisition Module, you need to parse the result yourself
        // Refer to the code and message mapping in this README. The data field contains detailed result information.
    });

  4. Refer to the Example Project

    For details, see the Android/example project.

iOS Integration​

  1. Import the Framework

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

  2. Configure Camera Permissions

    In your Info.plist file, add the Privacy - Camera Usage Description key and provide a user-facing explanation for why camera access is needed.

  3. Brief Usage Example

    let params = PalmMobileManagerParams(
        token: token,
        userId: userId,
        userName: userName,
        phoneNo: phoneNo,
    )
    // Set the mode (optional, defaults to registration)
    // params.mode = .verification
    // params.targetUserId = TARGET_USER_ID
    // You can also set your own Tencent PalmAI Platform server config.
    // 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 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 start the Management Module or the Acquisition Module
    // - true: Start the Management Module (Default)
    // - false: Start the Acquisition Module
    // params.enableManager = true
    // Specify which palm to use (.left / .right / .unspecified)
    // params.palmDirection = .unspecified
    PalmMobileManager.start(
        from: controller,
        params: params,
        completion: { result in
            // TODO: Handle business logic based on result.code
            print("PalmMobileManager succeed: \(result.code): \(result.message): \(result.data)")

            // When using the Acquisition Module, you need to parse the result yourself
            // Refer to the code and message mapping in this README. The data field contains detailed result information.
        }
    )

  4. Refer to the Example Project

    For details, see the iOS/example project.

Flutter Integration​

  1. Import the Plugin

    Place the flutter/palm_mobile_manager directory into a packages directory within your project (create it if it doesn't exist).

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

  2. Add the Dependency

    In your [YOUR_FLUTTER_APP]/pubspec.yaml, add a local path dependency:

    dependencies:
        flutter:
            sdk: flutter

    # ... other dependencies
    palm_mobile_manager:
        path: packages/palm_mobile_manager
        version: 0.0.0-dev

  3. Add Android LocalMavenRepo Path

    In your [YOUR_FLUTTER_APP]/android/build.gradle.kts (or build.gradle), add the Maven repository path:

    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 Permissions

    In [YOUR_FLUTTER_APP]/iOS/Runner/Info.plist, add NSCameraUsageDescription:

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

  5. Brief Usage Example

    final params = Params(
      token: _tokenController.text,
      userId: _userIdController.text,
      phoneNo: _phoneNoController.text,
      userName: _userNameController.text,
      // Set the mode (optional, defaults to REGISTRATION)
      // mode: Mode.verification,
      // targetUserId: TARGET_USER_ID,
      // You can also set your own Tencent PalmAI Platform server config.
      // 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 JWT Token)
      // customHeaders: {'Authorization': 'YOUR_JWT_TOKEN'},
      // You can choose whether to upload the video
      // enableVideoUpload: true,
      // You can choose to start the Management Module or the Acquisition Module
      // - true: Start the Management Module (Default)
      // - false: Start the Acquisition Module
      // enableManager: true,
      // Specify which palm to use (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. Refer to the Example Project

    For details, see the flutter/palm_mobile_manager/example project.

  7. First-Time Opening of the Example iOS Project (Important)

    example/ios/Pods/, example/ios/Flutter/Generated.xcconfig, .dart_tool/, etc. are local build outputs excluded by .gitignore and are NOT included in the SDK package / repository. Opening example/ios/Runner.xcworkspace directly with Xcode will fail with:

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

    This is the standard behavior of any Flutter plugin project (independent of the SDK version). Run the following three steps under flutter/palm_mobile_manager/ (pod install consumes the Generated.xcconfig produced by the previous step, so the order matters):

    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 with Xcode and it will build normally.

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

API Reference​

Params​

Configuration object for starting the SDK.

Note: When passing required and optional parameters to start the SDK, only non-null and validity checks are performed; otherwise, code=10001 is returned. Integrators should follow the format requirements below; otherwise, network-related errors will be displayed to users in the Management Module.

Required Parameters​

ParameterTypeDescription
tokenStringUser identity token for authorizing this SDK operation.
userIdStringUser's unique identifier.
Format: 1-64 characters. Only ASCII letters (A-Z, a-z), digits (0-9), hyphens (-), and underscores (_) are allowed. No spaces or whitespace.
userNameStringUser's name.
Format: 1-64 Unicode characters. Cannot consist solely of whitespace. No leading or trailing spaces allowed (spaces between characters are permitted). Supports desensitization.
phoneNoStringUser's phone number.
Format: Numbers only (4-20 digits), including country code (1-3 digits), e.g., (+86)13800138000. Supports desensitization.

Optional Parameters​

ParameterTypeDefaultDescription
modeModeREGISTRATIONBusiness mode. Options:
• REGISTRATION - Registration mode
• VERIFICATION - Verification mode (1:1)
• RECOGNITION - Recognition mode (1:N)
targetUserIdString-Target user ID to verify against.
Note: Required when mode is VERIFICATION.
appIdint223Application ID, provided by service provider.
baseUrlStringhttps://app.intl.palm.tencent.comAPI service address.
enableVideoUploadBooleantrueWhether to upload acquisition video.
enableManagerBooleantrueWhether to start the Management Module. When true, starts the Management Module; when false, starts the Acquisition Module.
customHeadersMap<String, String>-Custom HTTP request headers. Used to access the gateway corresponding to your configured BaseUrl (e.g., pass JWT Token).
palmDirectionStringunspecifiedWhich palm to use during acquisition. Options:
• unspecified - Either palm is allowed (default)
• left - Force left palm
• right - Force right palm

Result​

Result object returned via callback when the SDK exits.

PropertyTypeDescription
codeintResult code. See callback result codes below.
messageStringDescriptive message for debugging only.

Callback Result Codes​

The Management Module automatically handles most results from the Acquisition Module. Your app will only receive callbacks for the following result codes:

CodeScenarioHandling Suggestion
0Operation successful or user manually returnsNo action needed
10001Invalid parametersCheck if parameters are valid, such as whether required fields are empty, whether BaseUrl is valid, etc.
10012Invalid or expired TokenRe-obtain Token
10401Gateway authentication failed for specified BaseUrlContact the BaseUrl provider for technical support, or add your gateway's JWT authentication information

Complete Result Code Reference​

Note: Acquisition Module does not capture result codes for internal handling. Complete result codes are as follows:

Click to expand all result codes
Common Result Codes​
CodeDeveloper Notes
0Operation successful (will callback)
10000Unknown error
10001Invalid parameters (will callback)
10002User cancelled acquisition operation
10003Camera permission denied
10004Camera initialization failed
10005Unsupported camera preview size
10006SDK initialization failed
10007SDK runtime error
10008Acquisition timeout (30 seconds timeout)
10012Invalid or expired Token (will callback)
10016Authorization certificate validation failed
10017Invalid UserName format
10018Invalid UserId format
10019Invalid Phone Number format
10021UserName does not exist
10022Tenant has disabled user registration
10023Phone number already exists under the tenant
10024Tenant has disabled palm registration
Registration Mode Result Codes​
CodeDeveloper Notes
10100Liveness detection failed
10101Quality check failed
10102Liveness video verification failed
10103Palm already registered
10104High similarity with existing user
Recognition Mode Result Codes​
CodeDescription
10200User not recognized
Verification Mode Result Codes​
CodeDescription
10200Feature not found for target user
10300Target user not found
10301Target user has not registered palm
10302Target user has not registered current palm direction
Network Result Codes​
CodeDescription
10401Unauthorized gateway access (will callback)
10500Network error

Security Warning​

Production Environment Security Requirements​

NEVER hardcode SecretId or SecretKey in production client code!

This exposes your platform account credentials to all users, allowing attackers to exploit them and cause severe damage to your services.

Correct Approach (Production):

Management Module

Acquisition Module

Quick Start for Testing Environments​

For local development / internal testing / isolated demo environments only. Demonstrates how to quickly obtain a Token:

/**
 * [For Testing Only] Quick token fetch and SDK start
 * WARNING: In production, tokens MUST come 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);  // Start SDK with Token
        }

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

Note: AppId/BaseUrl/SecretId/SecretKey must be used as a matching set. Contact technical support for test credentials.

Next Steps & Support​

  • Review the Example Projects: We strongly recommend that you compile and run the example project for your target platform before integration. This will help you quickly understand the SDK's complete workflow.
  • Get Technical Support: If you encounter any issues during integration, please contact your technical support representative.