使用说明

本文介绍如何在你的项目中集成和使用远鉴人脸活体检测插件。

技术原理

远鉴人脸活体检测插件是对活体检测核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor 方法，传入指定的 key 和 value 参数，你可以快速集成远鉴的活体检测能力。

setExtensionPropertyWithVendor 方法的 key 参数与远鉴的 API 名称完全对应，value 参数以 JSON 格式包装该 API 的部分或全部参数。因此，调用该方法时只要传入指定的 key 和 value，就可以调用对应的远鉴 API，实现活体检测的有关功能。

前提条件

iOS 开发环境需满足以下要求：

• Xcode 9.0 或以上版本。
• 运行 iOS 9.0 或以上版本的真机（非模拟器）。

示例项目

远鉴人脸活体检测插件提供了 GitHub 示例项目，你可以前往克隆或下载并进行体验。

平台	语言	示例代码
Android	Java	FosaferAgoraDemo/android
iOS	Objective-C	FosaferAgoraDemo/ios

运行步骤

参考以下步骤快速跑通示例项目：

1. 克隆仓库：

   Shell

   git clone -b ios https://github.com/AgoraIO-Usecase/FosaferAgoraDemo.git

2. 进入声网控制台 > 云市场页面，下载远鉴人脸活体检测插件的 iOS 插件包。解压后，将所有 .framework 库文件保存到 FOSAgora/FOSAgoraDemo。

3. 在终端中进入 FosaferAgoraDemo/FOSAgora，运行以下命令使用 CocoaPods 安装依赖：

   Shell

   pod install

4. 在 Xcode 中打开项目 FOSAgora/FOSAgoraDemo.xcworkspace。

5. 打开 FOSDetectViewController.m，进行如下修改：

   • 将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开通服务。
   • 将 <YOUR_APP_KEY> 和 <YOUR_APP_SECRET> 分别替换为你的 appKey 和 appSecret。获取方式详见购买和激活插件。
   Objective-C

   #define App_id @"<YOUR_APP_ID>"
   #define App_Key @"<YOUR_APP_KEY>"
   #define App_Secret @"<YOUR_SECRET>"

6. 连接一台 iOS 真机（非模拟器），运行项目。

预期效果

运行成功后，示例项目会安装到你的设备上。

1. 启动 App，你可以在界面上看到开始识别按钮。
2. 点击开始识别开始活体校验。

集成和调用流程

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网视频 SDK 和远鉴人脸活体检测插件。

1.1 使用声网 SDK 实现音视频互动

插件需要与 RTC SDK 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动：

实现音视频互动

1.2 购买和激活插件

你需要进入声网控制台 > 云市场页面，按照提示购买远鉴人脸活体检测插件。购买后需要保存好获取到的 appKey 和 appSecret，用于后续初始化插件。

1.3 集成插件

参考以下步骤集成插件：

1. 进入声网控制台 > 云市场页面下载远鉴人脸活体检测插件的 iOS 插件包。解压后，将所有 .framework 库文件保存到你的项目文件夹下。以如下项目结构为例，你可以把库文件保存到 <ProjectName> 路径下。

   Shell

   .
   ├── <ProjectName>
   ├── <ProjectName>.xcodeproj

2. 在 Xcode 中添加动态库，确保 Embed 属性设置为 Embed & Sign。

1.4 升级插件

声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理，从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时，会出现 App 闪退、崩溃等现象。

以下是用 SQLite 来进行插件版本管理的示例：

1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
2. 每次项目初始化时，自动检测当前项目使用的资源包版本：
   • 如果无记录文件或记录的资源包版本为旧，则更新资源。成功更新后，回写最新资源包版本信息到 SQLite。
   • 如果记录的资源包版本与当前匹配，则正常实现业务。

如果你的项目已经集成过声网云市场提供的第三方插件，并需要更新插件，可以参考以下步骤来保证更新后的可用性。

以下升级流程以相芯美颜特效插件为例：

1. 参考集成插件章节下载所需平台最新版本的插件包和资源包。

2. 删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。

3. 删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

注意

编译 App 时，系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行，否则可能会出现插件版本与资源包不匹配的情况，从而导致各种意外问题。

2. 启用插件

按照示例项目中 FOSDetectViewController.m 中的 initRtcEngine 方法，启动插件。

Objective-C

AgoraRtcEngineConfig *config = [AgoraRtcEngineConfig new];
config.eventDelegate = self;
config.appId = App_id;
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:config delegate:self];

[self.agoraKit enableExtensionWithVendor:@"fosafer"
                               extension:@"alive"
                                 enabled:YES];
[self.agoraKit enableVideo];
[self.agoraKit setChannelProfile:AgoraChannelProfileLiveBroadcasting];
[self.agoraKit setClientRole:AgoraClientRoleBroadcaster];
AgoraRtcVideoCanvas *canvas = [AgoraRtcVideoCanvas new];
canvas.view = self.preview;
[self.agoraKit setupLocalVideo:canvas];
[self.agoraKit startPreview];

3. 初始化插件

initRtcEngine 方法中实现 key 为 set_appKey_appSecret 的 setExtensionPropertyWithVendor 方法，设置 appKey 和 appSecret。

Objective-C

#define App_Key @""
#define App_Secret @""

给插件设置 appKey 和 appSecret：

Objective-C

NSDictionary *propertyDic = @{@"appKey" : App_Key, @"appSecret" : App_Secret};
NSData *propertyData = [NSJSONSerialization dataWithJSONObject:propertyDic
                                                       options:0
                                                         error:0];
NSString *propertyStr = [[NSString alloc] initWithData:propertyData
                                              encoding:NSUTF8StringEncoding];
[self.agoraKit setExtensionPropertyWithVendor:@"fosafer"
                                    extension:@"alive"
                                          key:@"set_appKey_appSecret"
                                        value:propertyStr];

4. 接收识别结果

在 onEvent 回调方法中，根据返回的数据，做对应的处理。

Objective-C

- (void)onEvent:(NSString *__nullable)provider
      extension:(NSString *__nullable)extension
            key:(NSString *__nullable)key
          value:(NSString *__nullable)value {
    NSData *jsonData = [value dataUsingEncoding:NSUTF8StringEncoding];
    NSError *err;
    NSDictionary *dic =
        [NSJSONSerialization JSONObjectWithData:jsonData
                                        options:NSJSONReadingMutableContainers
                                          error:&err];
    if (!err) {
        NSString *errorCode = [dic objectForKey:@"errorCode"];
        NSString *message = [dic objectForKey:@"message"];
        switch (errorCode.integerValue) {
            case 0:
                NSLog(@"成功");
                [self detectSuccessAction];
                break;
            case 1001:
                [self timeoutAction];
                break;
            case 1002:
                [self alertTitle:@"提示"
                         message:@"打开引擎库失败,请重试"
                            type:1];
                break;
            case 1003:
                [self alertTitle:@"提示"
                         message:@"引擎库返回人脸图片为空,请重试"
                            type:1];
                break;
            case 1004:
                [self alertTitle:@"提示"
                         message:@"setProperty方法参数格式错误"
                            type:1];
                break;
            case 1005:
                [self alertTitle:@"提示" message:@"appKey不能为空" type:1];
                break;
            case 1006:
                [self alertTitle:@"提示" message:@"appSecret不能为空" type:1];
                break;
            case 2000:
                [self setTips:@"正在处理"];
                [self.agoraKit enableLocalVideo:NO];
                break;
            case 2001:
                [self setTips:@"请在检测框中露出人脸"];
                break;
            case 2002:
                [self setTips:@"请在检测框中露出人脸"];
                break;
            case 2003:
                [self setTips:@"靠近点"];
                break;
            case 2004:
                [self setTips:@"离远点"];
                break;
            case 2005:
                [self setTips:@"环境过暗"];
                break;
            case 2006:
                [self setTips:@"环境过亮"];
                break;
            case 2007:
                [self setTips:@"请保持稳定"];
                break;
            case 2008:
                [self setTips:@"请保持手机竖直"];
                break;
            case 3001:
                [self alertTitle:@"提示" message:message type:1];
                break;
            case 3002:
                [self alertTitle:@"提示" message:message type:1];
                break;

            default:
                break;
        }
    }
}

5. 释放插件

当检测完成，需要关闭检测页面时，需要调用 FOSDetectViewController.m 中的 destroy 方法，用以释放插件内存。

Objective-C

- (void)destroy {
    [self.agoraKit stopPreview];
    [self.agoraKit enableLocalVideo:NO];
    [AgoraRtcEngineKit destroy];
}

API 参考

• 声网 SDK 的插件相关方法和回调
• 插件的 key-value 说明