更新记录

1.0.0（2026-05-09）

初始化发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

XF-aliFaceDetectUTS 封装了阿里云金融级实人认证 SDK 在 Android、iOS 和 Harmony 系统中获取设备 metaInfo、拉起实人认证流程的逻辑。

客户端只负责获取 metaInfo 和使用服务端返回的 certifyId 拉起认证。姓名、证件号、AccessKey、Secret、服务端签名参数等敏感信息不要放在客户端。

插件接口

getMetaInfo

获取阿里云实人认证初始化需要的设备 metaInfo。

业务服务端需要使用 metaInfo、姓名、证件号等信息调用阿里云认证初始化接口，换取 certifyId。

uni-app项目中（nvue）调用示例：

import { getMetaInfo } from "@/uni_modules/XF-aliFaceDetectUTS"

const metaInfo = getMetaInfo()
console.log(metaInfo)

uni-app x项目（uvue）中调用示例：

import { getMetaInfo } from "@/uni_modules/XF-aliFaceDetectUTS";

const metaInfo = getMetaInfo();
console.log(metaInfo);

可用性

iOS、Android、Harmony系统

可提供的1.0.0及更高版本

startVerify

使用服务端返回的 certifyId 拉起阿里云实人认证页面。

startVerify 的成功回调只表示 SDK 本次采集流程返回成功码。业务最终是否通过认证，应以服务端查询阿里云认证结果为准。

uni-app项目中（nvue）调用示例：

import { startVerify } from "@/uni_modules/XF-aliFaceDetectUTS"

startVerify({
  certifyId: "",
  extParams: {
    // 可选扩展参数。iOS 会自动注入 currentCtr，无需业务侧传入。
  },
  success: (res) => {
    console.log("verify success", res)
  },
  fail: (err) => {
    console.error("verify fail", err)
  },
  complete: (res) => {
    console.log("verify complete", res)
  }
});

uni-app x项目（uvue）中调用示例：

import { startVerify } from "@/uni_modules/XF-aliFaceDetectUTS";
import { AliFaceDetectStartVerifyOptions } from "@/uni_modules/XF-aliFaceDetectUTS/utssdk/interface.uts";

let options = {
  certifyId: "",
  extParams: {
    // 可选扩展参数。iOS 会自动注入 currentCtr，无需业务侧传入。
  },
  success: (res : any) => {
    console.log("verify success", res)
  },
  fail: (err : any) => {
    console.error("verify fail", err)
  },
  complete: (res : any) => {
    console.log("verify complete", res)
  }
} as AliFaceDetectStartVerifyOptions;

startVerify(options);

参数说明

返回值

type AliFaceDetectVerifyResult = {
  errMsg : string
  certifyId ?: string | null
  code ?: string | null
  subCode ?: string | null
  reason ?: string | null
  message ?: string | null
  deviceToken ?: string | null
  videoFilePath ?: string | null
  photinusVideoFilePath ?: string | null
  extInfo ?: UTSJSONObject | null
}

可用性

iOS、Android、Harmony系统

可提供的1.0.0及更高版本

认证流程

1. 客户端调用 getMetaInfo() 获取设备 metaInfo。
2. 业务服务端使用 metaInfo、姓名、证件号调用阿里云认证初始化接口，获取 certifyId。
3. 客户端调用 startVerify({ certifyId }) 拉起阿里云 SDK 认证页面。
4. 客户端收到 SDK 回调后，业务服务端再查询最终认证结果。

宿主权限

请在宿主应用配置中补充 SDK 需要的权限说明。

Android 常用权限由 AAR Manifest 合并，重点包括：

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE
• android.permission.CAMERA
• android.permission.RECORD_AUDIO
• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_WIFI_STATE
• android.permission.NFC
• android.permission.FOREGROUND_SERVICE

iOS 需要在 Info.plist 中配置：

• NSCameraUsageDescription
• NSMicrophoneUsageDescription

Harmony 需要在 harmony-configs/entry/src/main/module.json5 中配置：

• ohos.permission.INTERNET
• ohos.permission.CAMERA
• ohos.permission.MICROPHONE

错误码