SDK-接入文档(ios版)

此文档只适用于FaceID MegLiveStill SDK 2.0.0及以上版本，SDK 1.3版本及以下版本请参考对应历史文档。

类MGFaceIDLiveDetectManager

初始化函数initFaceIdManagerWithToken

函数名initMGFaceIDLiveDetectManagerWithBizToken
方法描述-
(instancetype _Nullable)initMGFaceIDLiveDetectManagerWithBizToken:(NSString *__nonnull)bizTokenStr
language:(MGFaceIDLiveDetectLanguageType)languageType
networkHost:(NSString *__nullable)hostUrl
extraData:(NSDictionary *__nullable)extraDict
error:(MGFaceIDLiveDetectError _Nullable__nonnull)error;
名称获取活体检测管理类对象
说明传入bizTokenStr、languageType 、hostUrl 、extraDict、error获取管理类对象接口
变量名说明
bizTokenStr类型： NSString *
说明：业务流水号，每次验证前，通过服务端API获取的流水号（bizToken）
languageType类型： MGFaceIDLiveDetectLanguageType
说明： 选择语言种类。详见MGFaceIDLiveDetectLanguageType
hostUrl类型： NSString *
说明：网络请求host地址。host取值见附录E 【host取值列表】，请根据具体情况选择host取值。
extraDict类型： NSDictionary*
说明：预留参数，暂时无使用。
error类型：MGFaceIDLiveDetectError*
说明：错误信息结构体，详细见下方MGFaceIDLiveDetectError 说明

函数getSDKVersion

函数名getSDKVersion
方法描述+ (NSString *__Nonnull)getSDKVersion;
名称获取SDK的版本号
说明无
返回值一个字符串，表示当前SDK的版本号。如：MegLiveStill 2.0.0

函数getSdkBuildInfo

此函是为非必须函数，获取的SDK构筑信息便于后期定位问题，建议使用；

函数名getSdkBuildInfo
方法描述+ (NSString *__Nonnull) getSDKBuild;
名称获取SDK的构筑信息
类型说明函数
说明无
返回值NSString*， 一个字符串。

函数startMGFaceIDLiveDetectWithCurrentController

函数名startMGFaceIDLiveDetectWithCurrentController
方法描述-(void)startMGFaceIDLiveDetectWithCurrentController:(UIViewController *__nonnull)detectVC
callback:(MGFaceIDLiveDetectResultBlock __nonnull)block
名称开启活体检测
类型说明函数
说明注：仅当获取MGFaceIDLiveDetectManager 中的error 结构体中MGFaceIDLiveDetectErrorNone=1000才能开启检测
变量名说明
detectVC类型： UIViewController *
说明： 启动认证的UI界面
block类型： MGFaceIDLiveDetectResultBlock
说明：检测结果的回调函数MGFaceIDLiveDetectResultBlock对象,详见回调函数MGFaceIDLiveDetectResultBlock介绍

MGFaceIDLiveDetectResultBlock的回调函数

函数名MGFaceIDLiveDetectResultBlock
方法描述typedef void(^MGFaceIDLiveDetectResultBlock)(MGFaceIDLiveDetectError* error, NSData* deltaData, NSString* bizTokenStr, NSDictionary* extraOutDataDict)
名称回调函数
类型说明函数
说明无
变量名说明
error类型：MGFaceIDLiveDetectError *
说明：错误信息结构体，详细见下方MGFaceIDLiveDetectError 说明
deltaData类型： NSData*
说明：客户端验证后数据。注：需用该data调用服务端接口进行数据验证。
bizTokenStr类型： NSString*
说明：业务流水号，每次验证前，通过服务端API获取的流水号（bizToken）。
extraOutDataDict类型： NSDictionary*
说明：预留字段，暂时无用，无需处理。

函数setMGFaceIDLiveDetectCustomUIConfig

函数名setMGFaceIDLiveDetectCustomUIConfig
方法描述设置FaceID 活体检测的自定义UI效果
名称- (void)setMGFaceIDLiveDetectCustomUIConfig:(MGFaceIDLiveDetectCustomConfigItem *__nullable)configItem;
类型说明函数
说明设置FaceID 活体检测的自定义UI效果
变量名说明
configItem类型： MGFaceIDLiveDetectCustomConfigItem *
说明：自定义UI配置

函数setMGFaceIDLiveDetectPhoneVertical

函数名setMGFaceIDLiveDetectPhoneVertical
方法描述- (void)setMGFaceIDLiveDetectPhoneVertical:(MGFaceIDLiveDetectPhoneVerticalType)verticalType;
名称设置活体检测的手机垂直检测类型
类型说明函数
说明设置活体检测的手机垂直检测类型
变量名说明
verticalType类型： MGFaceIDLiveDetectPhoneVerticalType
说明： 垂直检测枚举类型

垂直检测类型的枚举 MGFaceIDLiveDetectPhoneVerticalType

typedef enum : NSUInteger {
    MGFaceIDLiveDetectPhoneVerticalFront            = 0,            //  仅在开始的2s内启用，2s后关闭该功能
    MGFaceIDLiveDetectPhoneVerticalContinue         = 1,            //  持续启用
    MGFaceIDLiveDetectPhoneVerticalDisable          = 2,            //  禁用
} MGFaceIDLiveDetectPhoneVerticalType;

错误类型MGFaceIDLiveDetectError说明

类成员说明
MGFaceIDLiveDetectErrorType errorType错误信息枚举，详见枚举说明
NSString* errorMessageStr错误信息

枚举MGFaceIDLiveDetectErrorType

类型名MGFaceIDLiveDetectErrorType
名称活体认证失败类型
类型说明枚举类型

说明

枚举名说明Error message
MGFaceIDLiveDetectErrorNone = 1000没有错误 SDK 活体检测完成LIVENESS_FINISH
MGFaceIDLiveDetectErrorIllegalParameter = 4200传入的参数不合法ILLEGAL_PARAMETER
MGFaceIDLiveDetectErrorBizTokenDenied = 4200传入的biz_token不符合要求BIZ_TOKEN_DENIED
MGFaceIDLiveDetectErrorAuthenticationFail = 4200鉴权失败AUTHENTICATION_FAIL
MGFaceIDLiveDetectErrorMobilePhoneNotSupport = 4200手机不在支持列表里MOBILE_PHONE_NOT_SUPPORT
MGFaceIDLiveDetectErrorSDKTooOld = 4200SDK版本过旧，已经不被支持SDK_TOO_OLD
MGFaceIDLiveDetectErrorUserCancel = 6000用户取消活体检测USER_CANCEL
MGFaceIDLiveDetectErrorNotResource = 6000未添加资源包NOT_ADD_RESOURCE
MGFaceIDLiveDetectErrorNotCameraPermission = 6000APP没有获取相机权限NO_CAMERA_PERMISSION
MGFaceIDLiveDetectErrorNotCameraSupport = 6000APP未找到可用的相机设备DEVICE_NOT_SUPPORT
MGFaceIDLiveDetectErrorFaceInitFail = 6000SDK活体检测启动失败FACE_INIT_FAIL
MGFaceIDLiveDetectErrorNetWorkNotConnected = 6000连不上互联网，请检查网络连接状态NETWORK_ERROR
MGFaceIDLiveDetectErrorOnvalidBundleID = 6000APP信息验证失败，请检测bundleID设置ONVALID_BUNDLEID
MGFaceIDLiveDetectErrorLiveFail = 6000SDK 活体检测失败LIVENESS_FAILURE
MGFaceIDLiveDetectErrorGoToBackground = 6000应用退到后台，活体检测失败GO_TO_BACKGROUND
MGFaceIDLiveDetectErrorUnknown = 6200未知错误ERROR_UNKNOWN
MGFaceIDLiveDetectErrorTimeOut = 9000操作超时，由于用户在长时间没有进行操作LIVENESS_TIME_OUT

枚举MGFaceIDLiveDetectLanguageType

类型名MGFaceIDLiveDetectLanguageType
名称活体语言种类
类型说明枚举类型

说明：

枚举名说明文件路径
MGFaceIDLiveDetectLanguageCh = 0中文ch
MGFaceIDLiveDetectLanguageEn = 1英文en

SDK介绍

SDK 版本： MegLiveStill 2.0.0I

模型说明：

  • 模型Meg_ActionLive。
  • 模型是 SDK 的核心组件，在 MGFaceIDDetectResource.bundle 中。

SDK 集成要求：

  • SDK支持的系统最低要求是 iOS 8.0，只支持真机架构 (arm64和armv7)，不支持模拟器架构 (x86_64和i386)。

SDK 集成说明：

  • 1、添加Framework 文件到项目：在Xcode工具中点击TARGETS->Build Phases-> Link Binary With Libaries中点击“+”按钮，在弹出的窗口中点击“Add Other”按钮，选择 MGFaceIDBaseKit.framework和MGFaceIDLiveDetect.framework 同时添加到工程中。

    注:

    静态库中采用Objective-C++实现，因此需要您保证您工程中至少有一个.mm后缀的源文件(您可以将任意一个.m后缀的文件改名为.mm)，或者在工程属性中指定编译方式，即在Xcode的Project -> Edit Active Target -> Build Setting 中找到Compile Sources As，并将其设置为"Objective-C++"

  • 2、引入所需的系统库：需要在您的Xcode工程中引入AVFoundation.framework、CoreMedia.framework、CoreMotion.framework、SystemConfiguration.framework系统库。

  • 3、环境配置：在 TARGETS->Build Settings->Other Linker Flags中添加 -ObjC;

  • 4、引入 .bundle 资源文件：选中工程名，在右键菜单中选择Add Files to “工程名”…，选择 bundle文件，并勾选“Copy items if needed”复选框，单击“Add”按钮，将资源文件添加到工程中，需要勾选 (Add to targets) 到指定的 target。

  • 5、添加硬件权限：因相机需要，请在 info.plist 中添加 Privacy - Camera Usage Description权限。

集成注意事项：

  • 必须在网络连通的情况下使用，离线状态无法该 SDK 无法启动。

多语言支持

设置语种：

SDK初始化接口initMGFaceIDLiveDetectManagerWithBizToken:language:networkHost:extraData:error:增加语种参数和调用集群参数，SDK根据传入的语种设置language ，根据调用集群参数调用相应集群的服务。

参数按照Language codes-ISO 639标准传入，语种参数详见附录【ISO 639-1 语言列表】，调用集群参数见附录E【host取值列表】。

多语言资源补齐：

在资源包中提供中文和英文的文本、图片、音频等资源的模板。用户如果需要支持新的语言，按照给定的模板内容创建对应语言的各资源文件。SDK会根据用户传入的语种参数在对应的资源文件夹下读取资源（默认语言为中文）。

多语言资源补齐步骤如下：

（1）添加语言

​ a. 在MGFaceIDLiveDetectLanguageConfig.h 中在枚举中添加新的语言类型，并设置该语言对应的枚举数字。

​ b. 在bundle/languageconfiguration.plist 中添加新的语言Item，填写该Item的type（String类型）、enum（Number类型）和mask（String类型）。

​ 注：Item****的type****需与MGFaceIDLiveDetectLanguageConfig.h****中的语言类型一致，enum****的值需与MGFaceIDLiveDetectLanguageConfig.h****中枚举数字一致。

（2）添加该语言的语音资源

​ 在bundle/audio 下新建以该语言mask值命名的文件夹， 并按规则在文件夹下添加语音资源。语音资源列表见附录B【语音资源列表】.

（3）添加该语言的图片资源

​ 在bundle/image 下新建以该语言mask值命名的文件夹，并按规则在文件夹下添加图片资源。图片资源列表见附录C【图片资源列表】.

（4）添加该语言的文本资源

​ 在bundle/text 下新建以该语言mask值命名的文件夹，并在此文件夹下新建MGFaceIDDetection.strings文件，在文件中修改相应文案内容。文本资源列表见附录D【文本资源列表】.

​

资源异常情况说明：

  1. 如果用户指定了新的语言，但是没有添加对应的资源，直接在编译阶段触发断言崩溃，同时提示错误信息：没有找到对应的资源（注：该断言会同时在debug模式和release模式同时触发，请务必按照资源列表需求完整添加所有资源）。

  2. 如果用户添加了对应的资源，但是资源不符合模板中约定的规则。使用用户提供的资源直接显示，不提示信息。

UI定制

可定制的UI内容：

可定制的内容主要包括：控件颜色、文案内容、文案颜色、文案字号、图片资源、语音资源等。下文将逐个页面说明哪些UI元素可以修改。

1

  • 1、默认图片资源可以更换，素材名称：faceid_detect_remind_icon

  • 2、首页提示语文字颜色可替换 文案字体颜色变量名：livenessGuideRemindTextColor

  • 3、首页同意协议文字颜色可更换，变量名：livenessGuideReadColor

  • 4、button颜色可更换，文字颜色可以更换。

    button可选状态颜色变量名：livenessDetectButtonSelectedBGColor

    button不可选状态颜色变量名：livenessDetectButtonNormalBGColor

    button高亮状态颜色变量名：livenessDetectButtonHighlightBGColor

    字体颜色变量名：livenessDetectButtonTextColor

  • 5、背景色可以更换，变量名称：livenessHomeBackgroundColor

  • 6、右上角关闭按钮资源可以更换，变量名称：liveness_home_closeicon

  • 7、圆环部分背景色可以替换，变量名称：livenessHomeRingColor

  • 8、进度条颜色可以更换，变量名称：livenessHomeProcessBarColor

  • 9、验证失败后，进度条颜色可以更换，变量名称：livenessHomeValidationFailProcessBarColor

  • 10、圆圈下的字体颜色、字体大小、文案内容可以更换，此字体一直保持居中状态，支持折行； 文案字体颜色变量名：livenessHomePromptColor 文案字体大小变量名：livenessHomePromptSize 文案内容： “请让我看到您的正脸”：livenessHomePromptFrontalFaceText “验证中，请稍候”：livenessHomePromptWaitText “人脸有效面积太小”：livenessHomePromptFaceEreaText “请让光线再亮点”：livenessHomePromptBrighterText “请让光线再暗点”：livenessHomePromptDarkerText “请再靠近一些”：livenessHomePromptCloserText “请离屏幕远一些”：livenessHomePromptFurtherText “请避免侧光或背光”：livenessHomePromptNoBacklightingText “请将正脸置于取景框内”:livenessHomePromptFrontalFaceInBoundingBoxText “请勿遮挡眼睛”: livenessHomePromptNoEyesOcclusionText “请勿遮挡嘴巴”: livenessHomePromptNoMouthOcclusionText “很好，请保持不动”: livenessHomePromptStayStillText

    “请向左或向右缓慢转头”： livenessHomePromptShakeHeadText “请缓慢点头”： livenessHomePromptNodText “请张嘴” ： livenessHomePromptOpenMouthText “请眨眼”： livenessHomePromptBlinkText

  • 11、动作活体时语音资源可以替换： “请眨眼”：liveness_blink “请张嘴”：liveness_mouth_open “请向左或向右缓慢转头”：liveness_shakehead “请缓慢点头”：liveness_nod “很好”：liveness_well_done

  • 12、在loading过程中，loading效果素材可以更换；素材名称：liveness_home_loadingicon

  • 13、退出弹层标题内容、标题文案字号、颜色可以更换： 字体颜色变量名：livenessExitTitlePromptColor 字体大小变量名：livenessExitTitlePromptSize 文案内容： “确认退出吗”：livenessExitTitlePromptText

  • 14、退出弹层的中的左右两个选项的文案内容、文案字号、颜色可以更换： 左项： 字体颜色变量名：livenessExitLeftPromptColor 字体大小变量名：livenessExitLeftPromptSize 文案内容： “取消”：livenessExitLeftPromptText 右项： 字体颜色变量名：livenessExitRightPromptColor 字体大小变量名：livenessExitRightPromptSize 文案内容： “确定”：livenessExitRightPromptText

  • 15、图中动画内容可以替换： 眨眼动画： liveness_blink_eye_close liveness_blink_eye_open 张嘴动画： liveness_mouth_close liveness_mouth_open 点头动画： liveness_nod_down liveness_nod_up 摇头动画： liveness_shakehead_left liveness_shakehead_right

UI定制方法：

  • 修改尺寸、颜色： 创建一个实例对象，该对象中包括所有可配置信息。用户在使用SDK的时候，传入该对象。使用该对象中的信息渲染所有UI细节。 如果用户不创建该对象或者不更改对象中的任何可配置信息，使用默认的UI效果。
  • 修改文案内容： 在bundle/MGFaceIDDetection.strings中，修改文案内容。
  • 替换图片资源： 在bundle/image 文件夹中，替换图片资源。
  • 替换语音资源： 在bundle/audio 文件夹中，替换语音资源。

附录A：ISO 639-1语言列表

语言代码语言语言代码语言语言代码语言语言代码语言
aa阿法尔语fr法语li林堡语se北萨米语
ab阿布哈兹语fy弗里西亚语ln林加拉语sg桑戈语
ae阿维斯陀语ga爱尔兰语lo老挝语sh塞尔维亚-克罗地亚语
af南非语gd苏格兰盖尔语lt立陶宛语si僧加罗语
ak阿坎语gl加利西亚语lu卢巴语sk斯洛伐克语
am阿姆哈拉语gn瓜拉尼语lv拉脱维亚语sl斯洛文尼亚语
an阿拉贡语gu古吉拉特语mg马达加斯加语sm萨摩亚语
ar阿拉伯语gv马恩岛语mh马绍尔语sn绍纳语
as阿萨姆语ha豪萨语mi毛利语so索马里语
av阿瓦尔语he希伯来语mk马其顿语sq阿尔巴尼亚语
ay艾马拉语hi印地语ml马拉亚拉姆语sr塞尔维亚语
az阿塞拜疆语ho希里莫图语mn蒙古语ss斯瓦特语
ba巴什基尔语hr克罗地亚语mo摩尔达维亚语st南索托语
be白俄罗斯语ht海地克里奥尔语mr马拉提语su巽他语
bg保加利亚语hu匈牙利语ms马来语sv瑞典语
bh比哈尔语hy亚美尼亚语mt马耳他语sw斯瓦希里语
bi比斯拉马语hz赫雷罗语my缅甸语ta泰米尔语
bm班巴拉语ia国际语Ana瑙鲁语te泰卢固语
bn孟加拉国语in印尼语nb书面挪威语tg塔吉克斯坦语
bo藏语ie国际语End北恩德贝勒语th泰语
br布列塔尼语ig伊博语ne尼泊尔语ti提格里尼亚语
bs波斯尼亚语ii四川彝语（诺苏语）ng恩敦加语tk土库曼语
ca加泰隆语ik依努庇克语nl荷兰语tl他加禄语
ce车臣语io伊多语nn新挪威语tn塞茨瓦纳语
ch查莫罗语is冰岛语no挪威语to汤加语
co科西嘉语it意大利语nr南恩德贝勒语tr土耳其语
cr克里语iu因纽特语nv纳瓦霍语ts宗加语
cs捷克语ja日语ny尼扬贾语tt塔塔尔语
cu古教会斯拉夫语jv爪哇语oc奥克语tw特威语
cv楚瓦什语ka格鲁吉亚语oj奥吉布瓦语ty塔希提语
cy威尔士语kg刚果语om奥洛莫语ug维吾尔语
da丹麦语ki基库尤语or奥利亚语uk乌克兰语
de德语kj宽亚玛语os奥塞梯语ur乌尔都语
dv迪维希语kk哈萨克语pa旁遮普语uz乌兹别克语
dz不丹语kl格陵兰语pi巴利语ve文达语
ee埃维语km高棉语pl波兰语vi越南语
el现代希腊语kn卡纳达语ps普什图语vo沃拉普克语
en英语ko朝鲜语、韩语pt葡萄牙语wa沃伦语
eo世界语kr卡努里语qu凯楚亚语wo沃洛夫语
es西班牙语ks克什米尔语rm罗曼什语xh科萨语
et爱沙尼亚语ku库尔德语rn基隆迪语yi依地语
eu巴斯克语kv科米语ro罗马尼亚语yo约鲁巴语
fa波斯语kw康沃尔语ru俄语za壮语
ff富拉语ky吉尔吉斯语rw卢旺达语zh中文、汉语
fi芬兰语la拉丁语sa梵语zu祖鲁语
fj斐济语lb卢森堡语sc萨丁尼亚语
fo法罗语lg卢干达语

附录B：语音资源列表

Key释义
liveness_blink“请眨眼”
liveness_mouth_open“请张嘴”
liveness_shakehead“请向左或向右缓慢转头”
liveness_nod“请缓慢点头”
liveness_well_done“很好”

附录C：图片资源列表

Key释义
liveness_home_closeicon右上角关闭按钮资源
liveness_home_loadingicon在loading过程中，loading效果素材
liveness_blink_eye_close眨眼动画中的闭眼图片
liveness_blink_eye_open眨眼动画中的睁眼图片
liveness_mouth_close张嘴动画中的闭嘴图片
liveness_mouth_open张嘴动画中的张嘴图片
liveness_nod_down点头动画中的低头图片
liveness_nod_up点头动画中的抬头图片
liveness_shakehead_left摇头动画中的向左摇头图片
liveness_shakehead_right摇头动画中的向右摇头图片

附录D：文本资源列表

Key文案内容
livenessHomePromptFrontalFaceText“请让我看到您的正脸”
livenessHomePromptWaitText“验证中，请稍候”
livenessHomePromptFaceEreaText“人脸有效面积太小”
livenessHomePromptBrighterText“请让光线再亮点”
livenessHomePromptDarkerText“请让光线再暗点”
livenessHomePromptCloserText“请再靠近一些”
livenessHomePromptFurtherText“请离屏幕远一些”
livenessHomePromptNoBacklightingText“请避免侧光或背光”
livenessHomePromptFrontalFaceInBoundingBoxText“请将正脸置于取景框内”
livenessHomePromptNoEyesOcclusionText“请勿遮挡眼睛”
livenessHomePromptNoMouthOcclusionText“请勿遮挡嘴巴”
livenessHomePromptStayStillText“很好，请保持不动”
livenessHomePromptShakeHeadText“请向左或向右缓慢转头”
livenessHomePromptNodText“请缓慢点头”
livenessHomePromptOpenMouthText“请张嘴”
livenessHomePromptBlinkText“请眨眼”
livenessExitTitlePromptText“确认退出吗”
livenessExitLeftPromptText“取消”
livenessExitRightPromptText“确定”
livenessHomePromptTooBrightText“光线过亮，请到更暗的环境中验证”

附录E：host取值列表

Host取值含义
https://api.megvii.com中国集群。目前支持调用中国集群。

当前版本

  • v2.0.0

历史版本

← SDK-接入文档(android版)SDK-获取BizToken →