iOS SDK 文档
1、简介
人脸识别（Face Recognition），是一项提取人脸特征信息进行智能分析的生物识别技术，识别率高达99.4%，比肉眼更准确。 MSC SDK 中人脸识别（IdentityVerifier）功能，主要分为下面几种类型：
（1）人脸验证（Face Verification）——1:1 相似度对比 通过提取两张人脸的特征，进行相似度对比，最终返回相应的置信度得分，系统根据特征匹配程度决定“拒绝”或者“接受”。用于判断两个输入人脸是否属于同一人。
（2）人脸检索（Face Detection）——1:N相似度对比 在大规模人脸数据库中快速找出与待检索人脸相似度最高的一个或多个人脸。
人脸识别详细的接口介绍及说明请参考： MSC Android API 文档 ， 在集成过程中如有疑问，可登录讯飞开放平台论坛 ，查找答案或与其他开发者交流。
#2. 参数相关说明
在人脸识别过程的主要参数有：
- 人脸识别会话类型（MFV_SST）：会话类型，包括注册（enroll），验证（verify），删除（delete）
- 用户ID（AUTH_ID）：标识每个使用人脸功能的终端用户的唯一ID
- 业务场景（MFV_SCENES）：业务类型，人脸业务为ifr
其中人脸检测和聚焦是对任意人脸图片检测，与用户是否已注册无关，故不需要设置用户 ID。 识别结果通过 RequestListener 回调返回，其中包含了是否成功等信息，详细的 JSON 格式请参照人脸识别结果。
相关概念的说明如下：
| 名称 | 说明 |
|---|---|
| enroll/注册 | 上传包含一张人脸的图片到云端，引擎对其进行特征抽取，生成一个与之对应的模型，返回模型id(gid)。 |
| verify/验证 | 注册成功后，上传包含一张人脸的图片到云端，引擎将其与所注册的人脸模型进行比对，验证是否为同一个人，返回验证结果。 |
| delete/删除 | 删除注册的人脸模型 |
| auth_id/用户id | 由应用传入，用于标识用户身份，长度为6-18个字符（由英文字母、数字、下划线组成，不能以数字开头），注：注册和验证都必须指定auth_id. |
为了获得较高的准确率，请确保输入的图片满足以下要求：
| 项目 | 要求 |
|---|---|
| 色彩、格式 | 彩色，PNG、JPG、BMP格式的图片。 |
| 人脸大小 、角度 | 大小应超过100*100像素，可以容忍一定程度的侧脸，为保证识别准确率，最好使用正脸图片。 |
| 光照 | 均匀光照，可容忍部分阴影。 |
| 遮挡物 | 脸部尽量无遮挡，眼镜等物品会一定程度上影响准确率。 |
#3、SDK集成指南
#第一步：获取appid
appid是第三方应用集成讯飞开放平台SDK的身份标识，SDK静态库和appid是绑定的，每款应用必须保持唯一，否则会出现10407错误码。appid在开放平台申请应用时可以获得，下载SDK后可从SDK中sample文件夹的Demo工程里找到（例如: /sample/MSCDemo/MSCDemo/Definition.h 的APPID_VALUE）。
#第二步：工程配置
#添加库
将开发工具包中lib目录下的iflyMSC.framework添加到工程中。同时请将Demo中依赖的其他库也添加到工程中。 按下图示例添加 SDK 所需要的 iOS系统库：
| 库名称 | 添加范围 | 功能 |
|---|---|---|
| iflyMSC.framework | 必要 | 讯飞开放平台静态库。 |
| libz.tbd | 必要 | 用于压缩、加密算法。 |
| AVFoundation.framework | 必要 | 用于系统录音和播放 。 |
| SystemConfiguration.framework | 系统库 | 用于系统设置。 |
| Foundation.framework | 必要 | 基本库。 |
| CoreTelephony.framework | 必要 | 用于电话相关操作。 |
| AudioToolbox.framework | 必要 | 用于系统录音和播放。 |
| UIKit.framework | 必要 | 用于界面显示。 |
| CoreLocation.framework | 必要 | 用于定位。 |
| Contacts.framework | 必选 | 用于联系人。 |
| AddressBook.framework | 必选 | 用于联系人。 |
| QuartzCore.framework | 必要 | 用于界面显示。 |
| CoreGraphics.framework | 必要 | 用于界面显示。 |
| libc++.tbd | 必要 | 用于支持C++。 |
注意：
- 添加iflyMSC.framework时，请检查工程BuildSetting中的framwork path的设置，如果出现找不到framework的情况，可以将path清空，在Xcode中删除framework，然后重新添加。
- iflyMSC.framework最低支持iOS 8.0。
#设置Bitcode
在Xcode 7,8默认开启了Bitcode，而Bitcode 需要工程依赖的所有类库同时支持。MSC SDK暂时还不支持Bitcode，可以先临时关闭。后续MSC SDK支持Bitcode 时，会在讯飞开放平台上进行SDK版本更新，请关注。关闭此设置，只需在Targets - Build Settings 中搜索Bitcode 即可，找到相应选项，设置为NO。 
#用户隐私权限配置
iOS 10发布以来，苹果为了用户信息安全，加入隐私权限设置机制，让用户来选择是否允许。 隐私权限配置可在info.plist 新增相关privacy字段，MSC SDK中需要用到的权限主要包括麦克风权限、联系人权限和地理位置权限：
<key>NSMicrophoneUsageDescription</key>
<string></string>
<key>NSLocationUsageDescription</key>
<string></string>
<key>NSLocationAlwaysUsageDescription</key>
<string></string>
<key>NSContactsUsageDescription</key>
<string></string>
即在Info.plist 中增加下图设置： 
#第三步：初始化
初始化示例：
//Appid是应用的身份信息，具有唯一性，初始化时必须要传入Appid。
NSString *initString = [[NSString alloc] initWithFormat:@"appid=%@", @"YourAppid"];
[IFlySpeechUtility createUtility:initString];
| 参数 | 说明 | 必填 |
|---|---|---|
| appid | 8位16进制数字字符串，应用的唯一标识，与下载的SDK一一对应。 | 是 |
| usr | 保留字段，无需关注。 | 否 |
| pwd | 保留字段，无需关注。 | 否 |
注意： 初始化是一个异步过程，可放在App启动时执行初始化，具体代码可以参照Demo的MSCAppDelegate.m。
#第四步：启动服务
所有的服务皆遵循如下的流程，如下图：
所有服务的API详细说明可参见：https://www.xfyun.cn/doc/mscapi/iOS/iosverifier.html
#第五步：人脸注册
人脸注册,示例代码如下：
// 人脸参数
// 设置sub 参数请求业务类型
[self.identityVerifier setParameter:@"mfv" forKey:[IFlySpeechConstant MFV_SUB]];
// 设置scenes，ifr（人脸）
// 指明注册的特征种类
[self.identityVerifier setParameter:@"ifr" forKey:[IFlySpeechConstant MFV_SCENES]];
NSString* auth_id=self.authIdLabel.text;
[self.identityVerifier setParameter:@"enroll" forKey:[IFlySpeechConstant MFV_SST]];
// 设置delegate ,auth_id，开始会话
[self.identityVerifier setParameter:auth_id forKey:[IFlySpeechConstant MFV_AUTH_ID]];
[self.identityVerifier startWorking];
// 人脸数据参数
NSString* dwtParams=[NSString stringWithFormat:@"%@=%@,",[IFlySpeechConstant MFV_SST],@"enroll"];
dwtParams=[dwtParams stringByAppendingFormat:@"%@=%@,",[IFlySpeechConstant MFV_AUTH_ID],auth_id];
// 压缩人脸数据并写入
NSData* data=[self.face compressedData];
[self.identityVerifier write:@"ifr" data:data offset:0 length:(int)[data length] withParams:dwtParams];
[self.identityVerifier stopWrite:@"ifr"];
// 实现IFlyIdentityVerifierDelegate协议
// 消息回调
- (void)onEvent:(int)eventType arg1:(int)arg1 arg2:(int)arg2 extra:(id)obj;
// 结果回调，results中包含有json格式结果，字段说明参考附录身份验证结果说明。
- (void)onResults:(IFlyIdentityResult *)results isLast:(BOOL)isLast{}
// 结束回调，没有错误时，error为nil
- (void) onCompleted:(IFlySpeechError*) error{}
#第六步:人脸验证
人脸验证,示例代码如下：
// 设置会话场景
[self.identityVerifier setParameter:@"ifr" forKey:[IFlySpeechConstant MFV_SCENES]];
// 设置会话类型
[self.identityVerifier setParameter:@"verify" forKey:[IFlySpeechConstant MFV_SST]];
// 用户id
[self.identityVerifier setParameter:auth_id forKey:[IFlySpeechConstant MFV_AUTH_ID]];
// 人脸数据参数
NSString* dwtParams=[NSString stringWithFormat:@"%@=%@,",[IFlySpeechConstant MFV_AUTH_ID],auth_id];
dwtParams=[dwtParams stringByAppendingFormat:@"%@=%@,",[IFlySpeechConstant MFV_SST],@"verify"];
// 压缩人脸数据并写入
[self.identityVerifier startWorking];
NSData* data=[self.face compressedData];
[self.identityVerifier write:@"ifr" data:data offset:0 length:(int)[data length] withParams:dwtParams];
[self.identityVerifier stopWrite:@"ifr"];
// 实现IFlyIdentityVerifierDelegate协议
// 消息回调
- (void)onEvent:(int)eventType arg1:(int)arg1 arg2:(int)arg2 extra:(id)obj;
// 结果回调，results中包含有json格式结果，字段说明参考附录身份验证结果说明。
- (void)onResults:(IFlyIdentityResult *)results isLast:(BOOL)isLast{}
// 结束回调，没有错误时，error为nil
- (void) onCompleted:(IFlySpeechError*) error{}
#第七步:人脸删除
人脸验证,示例代码如下：
// 设置会话场景
[self.identityVerifier setParameter:@"ifr" forKey:[IFlySpeechConstant MFV_SCENES]];
// 用户id
[self.identityVerifier setParameter:auth_id forKey:[IFlySpeechConstant MFV_AUTH_ID]];
// 人脸数据参数
NSString* dwtParams=[NSString stringWithFormat:@"%@=%@,",[IFlySpeechConstant MFV_AUTH_ID],auth_id];
// 删除人脸数据
[self.identityVerifier execute:@"ifr" cmd:@"delete" params:dwtParams];
// 实现IFlyIdentityVerifierDelegate协议
// 消息回调
- (void)onEvent:(int)eventType arg1:(int)arg1 arg2:(int)arg2 extra:(id)obj;
// 结果回调，results中包含有json格式结果，字段说明参考附录身份验证结果说明。
- (void)onResults:(IFlyIdentityResult *)results isLast:(BOOL)isLast{}
// 结束回调，没有错误时，error为nil
- (void) onCompleted:(IFlySpeechError*) error{}
#4、人脸识别结果说明
| JSON字段 | 类型 | 说明 |
|---|---|---|
| sst | string | 指定本路会话是属于何种性质 |
| rst | bool | 结果 |
| sid | string | 会话id |
| ret | int | 错误码 |
| uid | string | 用户id |
#人脸注册字段
| JSON字段 | 类型 | 说明 |
|---|---|---|
| ssub | String | 业务类型，人脸业务为ifr（人脸验证） |
| sst | String | 子业务类型，注册业务为enroll |
| ret | int | 返回值，0为请求成功，其他为请求失败 |
| suc | int | 本次注册已成功的训练次数 |
| rgn | int | 本次注册需要的训练次数 |
| fid | String | 人脸模型id (当前无需关注) |
人脸注册结果示例：
{
"ret": 0,
"suc": 1,
"rgn": 1,
"sst": "enroll",
"ssub": "ifr",
"fid": "90f821fa7381ee297a80ed9570dea635"
}
#查询/删除模型字段
| JSON字段 | 类型 | 说明 |
|---|---|---|
| ssub | String | 业务类型，取值： ivp：声纹业务； ifr：人脸业务（暂无查询业务）； |
| ret | int | 返回值，0为请求成功，其他为请求失败 |
| sst | String | 子业务类型，取值： query：查询模型； delete：删除模型； |
查询结果示例 ：
{
"ssub": "ivp",
"sst": "query",
"ret": 0
}
删除结果示例：
{
"ssub": "ivp",
"sst": "delete",
"ret": 0
}
#5、视频教程
#6、常见问题
#人脸验证与检索支持什么应用平台？
答：目前提供SDK接口，支持：IOS/Android应用平台。
#人脸识别1:N检索功能介绍
答：人脸识别1:N相似度对比 在大规模人脸数据库中快速找出与待检索人脸相似度最高的一个或多个人脸。
#人脸验证与检索是否支持离线？
答：人脸验证与检索暂不支持离线环境，仅支持在线。
#人脸识别进行人脸验证出现11712错误
答：这个主要是人脸模型丢失或者模型未同步，建议删除重新注册。
#人脸验证与检索sdk怎么下载,免费服务量是多少？
答：登录讯飞开放平台，创建应用之后可在控制台左菜单栏--->其他--->人脸检索与验证下载相应的sdk，免费调用SDK接口500次服务量/天。