@faceaisdk/react-native-face-sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,13 +1,8 @@
 # @faceaisdk/react-native-face-sdk
 
-FaceAISDK 人脸识别、活体检测 React Native 原生插件仓库，支持 iOS 和 Android 双端，所有功能无需后台 API 服务即可离线运行。
+FaceAISDK 人脸识别、活体检测 React Native 原生插件，支持 iOS 和 Android 双端；所有功能无需后台 API 服务即可离线运行。
 
-当前仓库已调整为更接近标准 RN 库仓的结构：
-
-- **根目录**：可发布插件 `@faceaisdk/react-native-face-sdk`
-- **`example/`**：示例 App / 真机联调工程
-
-> **说明**：人脸识别、活体检测等功能需要摄像头，必须使用真机，不能在模拟器中验证。
+> ⚠️ **重要提示**：本 SDK 涉及底层硬件与原生算法，**必须使用真机测试**，模拟器无法运行。
 
 ## 安装
 
@@ -15,64 +10,29 @@ FaceAISDK 人脸识别、活体检测 React Native 原生插件仓库，支持 i
 npm install @faceaisdk/react-native-face-sdk
 ```
 
-### iOS
-
-在您的 iOS 工程目录下运行：
+### iOS 配置
 
-```sh
-cd ios
-pod install
-```
+1. 进入 iOS 目录并安装 Pod 依赖：
+   ```sh
+   cd ios && pod install
+   ```
+2. 在 `Info.plist` 中添加相机权限描述：
+   ```xml
+   <key>NSCameraUsageDescription</key>
+   <string>我们需要访问您的相机进行人脸识别与活体检测</string>
+   ```
 
-> **注意**：由于使用了人脸识别 SDK，您需要在 `Info.plist` 中添加相机权限描述：
-> ```xml
-> <key>NSCameraUsageDescription</key>
-> <string>我们需要访问您的相机进行人脸识别</string>
-> ```
+### Android 配置
 
-### Android
-
-1. 确保您的项目 `minSdkVersion` 至少为 24。
-2. Android 端会自动完成 Autolinking。
-
-> **注意**：由于使用了人脸识别 SDK，您需要在 `AndroidManifest.xml` 中确保有以下权限：
-> ```xml
-> <uses-permission android:name="android.permission.CAMERA" />
-> ```
+1. 确保项目的 `minSdkVersion` 至少为 **24**。
+2. 在 `AndroidManifest.xml` 中声明相机权限：
+   ```xml
+   <uses-permission android:name="android.permission.CAMERA" />
+   ```
 
 ---
 
-## 功能列表
-
-| 功能 | iOS | Android |
-|------|-----|---------|
-| SDK相机录入人脸信息 | ✅ | ✅ |
-| 1:1人脸识别+活体检测 | ✅ | ✅ |
-| 活体检测（动作/炫彩/静默） | ✅ | ✅ |
-| 查询人脸特征信息 | ✅ | ✅ |
-| 同步人脸特征信息 | ✅ | ✅ |
-| 图片录入人脸信息 | ✅ | ✅ |
-| 删除人脸特征信息 | ✅ | ✅ |
-
-## 仓库结构
-
-```text
-FaceAISDK_RN/
-├── src/                             # 插件 TypeScript 对外 API
-├── android/                         # 插件 Android Library 工程
-├── ios/                             # 插件 iOS 原生源码与资源
-├── @faceaisdk/react-native-face-sdk.podspec # iOS Podspec
-├── example/                         # 示例 App（真机调试、联调、回归）
-│   ├── App.tsx
-│   ├── android/
-│   ├── ios/
-│   └── auto_run.sh
-├── __tests__/                       # 插件单元测试
-├── README.md
-└── 插件封装与npm发布指南.md
-```
-
-## JS API
+## 功能与 API 说明
 
 根目录导出 Promise 风格接口：
 
@@ -88,165 +48,59 @@ import {
 } from '@faceaisdk/react-native-face-sdk';
 ```
 
-### 核心方法说明
+### 核心方法
 
 #### 1. SDK 相机录入人脸
-`addFaceBySDKCamera(faceID, options)`
+```ts
+addFaceBySDKCamera(faceID: string, options?: { mode?: number; showConfirm?: boolean }) => Promise<FaceResult>
+```
 - `faceID`: 用户唯一标识
-- `options`: `{ mode?: number, showConfirm?: boolean }`
+- `options`: 包含模式切换和是否展示确认弹窗。
 
 #### 2. 人脸比对 + 活体检测
-`faceVerify(faceID, options)`
-- `faceID`: 待验证的用户标识
-- `options`: 包含阈值、活体类型、动作序列、超时时间等配置
-
-#### 3. 纯活体检测
-`livenessVerify(options)`
-- 仅检测镜头前是否为活人，不进行 1:1 比对
-
-## 统一返回结构
-
 ```ts
-export interface FaceResult {
-  code: number;
-  msg: string;
-  faceID: string;
-  similarity: number;
-  liveness: number;
-  faceFeature: string;
-  faceBase64: string;
-}
-```
-
-## 状态码说明
-
-| Code | 含义 |
-|------|------|
-| 0 | 初始化状态/用户取消 |
-| 1 | 人脸识别对比成功（大于设置的 threshold） |
-| 2 | 人脸识别对比失败（小于设置的 threshold） |
-| 3 | 动作活体检测成功 |
-| 4 | 动作活体超时 |
-| 5 | 多次没有检测到人脸 |
-| 6 | 没有对应的人脸特征值 |
-| 7 | 炫彩活体成功 |
-| 8 | 炫彩活体失败 |
-| 9 | 炫彩活体失败（光线亮度过高） |
-| 10 | 所有活体检测完成 |
-| 11 | 静默活体检测失败 |
-| 12 | 没有录入人脸信息 |
-| 13 | 多人脸出现在镜头 |
-
-## 根目录：作为库开发/发布
-
-### 构建与测试
-
-```sh
-npm run typecheck
-npm run build
-npm test
-npm run pack
-```
-
-### 发布前检查
-
-```sh
-npm pack .
-```
-
-生成产物中应至少包含：
-
-- `src/` / `lib/`
-- `android/`
-- `ios/`
-- `@faceaisdk/react-native-face-sdk.podspec`
-
-## `example/`：作为示例 App 运行
-
-> 请确保已完成 [React Native 环境配置](https://reactnative.dev/docs/set-up-your-environment)。
-
-### 方式一：使用仓库根命令
-
-```sh
-npm run start
-npm run android
-npm run ios
+faceVerify(faceID: string, options?: FaceVerifyOptions) => Promise<FaceResult>
 ```
+- 包含相似度阈值、活体类型、动作序列、超时时间等配置。
 
-这些命令会自动代理到 `example/` 工程。
-
-### 方式二：直接进入 `example/`
-
-```sh
-cd example
-node ../node_modules/react-native/cli.js start --config metro.config.js
-```
-
-#### Android
-
-```sh
-cd example
-node ../node_modules/react-native/cli.js run-android --no-packager
-```
-
-#### iOS
-
-```sh
-cd example
-./pod-install.sh
-node ../node_modules/react-native/cli.js run-ios --device "您的手机名称"
-```
-
-如果您希望在仓库根目录执行，也可以直接运行：
-
-```sh
-npm run pods:install
-```
-
-`pod-install.sh` 会自动：
-
-- 使用 `example/vendor/bundle` 安装 Ruby gems
-- 注入 Ruby 4 所需的 `kconv` 兼容层
-- 对 `RCTSwiftUI` / `TensorFlowLiteSwift` 注入 `-no-verify-emitted-module-interface` 兼容参数（用于 Xcode 15.x）
-- 执行 `bundle exec pod install`
-
-### 真机自动运行脚本
-
-根目录保留了快捷入口，仍可直接执行：
-
-```sh
-./auto_run.sh
-```
-
-实际会转发到：
-
-```sh
-./example/auto_run.sh
+#### 3. 纯活体检测
+```ts
+livenessVerify(options?: LivenessVerifyOptions) => Promise<FaceResult>
 ```
+- 仅检测镜头前是否为活人，不进行 1:1 比对。
 
-## 示例工程如何消费本地库
+---
 
-`example/App.tsx` 使用包名方式调用本地根库：
+## 统一返回结构 (`FaceResult`)
 
 ```ts
-import {faceVerify} from '@faceaisdk/react-native-face-sdk';
+export interface FaceResult {
+  code: number;         // 状态码
+  msg: string;          // 提示文本
+  faceID: string;       // 用户标识
+  similarity: number;   // 比对相似度
+  liveness: number;     // 活体检测分值
+  faceFeature: string;  // 人脸特征值 (1024位)
+  faceBase64: string;   // 采集到的人脸图片 Base64 字符串
+}
 ```
 
-并通过 `example/metro.config.js` 将该包名解析到仓库根目录源码，便于在本地开发时即时调试。
+### 状态码 (`code`) 说明
 
-## 常见问题 (Troubleshooting)
+| Code | 含义 | Code | 含义 |
+|------|------|------|------|
+| **0** | 用户取消/初始化状态 | **7** | 炫彩活体成功 |
+| **1** | 人脸识别比对/录入成功 | **8** | 炫彩活体失败 |
+| **2** | 比对失败 (低于阈值) | **9** | 炫彩失败 (环境光过强) |
+| **3** | 动作活体检测成功 | **10** | 所有活体检测完成 |
+| **4** | 动作活体超时 | **11** | 静默活体检测失败 |
+| **5** | 多次未检测到人脸 | **12** | 对应人脸未录入 |
+| **6** | 对应人脸特征值不存在 | **13** | 镜头内出现多人脸 |
 
-### 1. 权限问题
-本插件需要相机权限。
-- **Android**: 插件会自动处理运行时权限请求，但您仍需确保 `AndroidManifest.xml` 中声明了权限。
-- **iOS**: 请务必在 `Info.plist` 中配置 `NSCameraUsageDescription`，否则 App 会在调用相机时崩溃。
+---
 
-### 2. 只有真机可用
-人脸识别和活体检测依赖底层硬件和原生 SDK，**模拟器无法运行**，请使用真机测试。
+## 贡献与本地开发
 
-### 3. 编译错误 (Xcode 15+)
-如果遇到 Swift 相关的编译错误，请参考 `example/pod-install.sh` 中的处理方式，确保开启了 `-no-verify-emitted-module-interface`。
+关于本地二次开发、本地示例工程运行、混合调试以及完整的 npm 发布流程，请参考开发说明文档：[插件封装与npm发布指南.md](./插件封装与npm发布指南.md)。
 
-## 许可证 (License)
 
-MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faceaisdk/react-native-face-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "React Native offline face enrollment, verification, and liveness detection SDK.",
   "license": "MIT",
   "author": "FaceAISDK.Service@gmail.com",