iOS接入_实人认证(ID Verification)-阿里云帮助中心

本文介绍人脸保镖方案的iOS端接入流程。

使用须知

重要

人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。
为帮助落实针对您产品集成第三方SDK情况所应履行的隐私合规义务，降低隐私违规风险，进而实现您产品合规运营的业务目标，请您务必确保选用阿里云文档中心官网发布的最新版本产品。在使用人脸保镖前，请您务必仔细了解个人信息处理规定及《SDK隐私权政策》。

iOS SDK使用限制如下：

不支持模拟器模式调试。
iOS系统版本为9.0及以上。
根据苹果官方隐私政策规定，需要 IDFA 的使用除了在 plist 中做相关说明之后，需要调用方主动弹框提示用户授权，因此开发环境需要确保是 Xcode 12 以上。

接入步骤

前期准备

接入前需要进行权限配置和SDK依赖配置，您可以参考下面的步骤操作。

权限说明

为增强人脸作弊的识别效果，当前 SDK 需要以下权限：

权限	是否必选	备注
NSLocalNetworkUsageDescription	是	获取局域网内设备连通性，用于发现设备牧场、群控等风险。
NSUserTrackingUsageDescription	否	用于获取 IDFA 信息，增强设备ID稳定性。

重要

请在Info.plist中添加 Privacy - Local Network Usage Description 说明，表示检测本地网络的连通性，可以根据您的产品属性进行内容微调。

依赖配置

下载 iOS SDK（请联系商务经理获取），SDK为XCode上标准静态framework包。
说明
- 单架构的 SO 文件在 2M 左右。
- 人脸保镖 SDK 为了保证自身的抗逆向性以及数据在网络传输过程中的安全性，SDK 中有大量的插花、膨胀及加解密操作，所以 SDK 体积会相对较大。
将 SDK 包中的 faceguard.framework 复制到 iOS 工程目录下。

选择工程配置，定位到 Build Phases -> Link Binary With Libraries，添加 faceguard.framework 及其依赖包：

AppTrackingTransparency.framework
CoreTelephony.framework
libresolv.tbd
Security.framework
AdSupport.framework
libz.tbd
libc++.tbd
faceguard.framework

调用SDK

前期准备完成后，可按照下面三个步骤完成客户端接入。

重要

根据苹果官方隐私政策规定，需要 IDFA 的使用除了在 plist 中做相关说明之后，需要调用方主动弹框提示用户授权，因此开发环境需要确保是 Xcode 12 以上。

初始化（initFG）
获取客户端Token（getDeviceToken）
携带Token请求服务端

初始化（initFG）

SDK 内部初始化，在 App 启动的时候，您需要尽可能早地调用该函数。

函数原型：

@interface FaceGuardDevice : NSObject

/**
 *  人脸保镖初始化函数
 */
- (void)initFG:(NSString *)userAppKey 
        withOptions:(NSMutableDictionary *)options
        callback:(void (^)(int))initCallback;
// ...
@end

调用示例

typedef void (^IDFARequestBlock)(bool success);

API_AVAILABLE(ios(14))
    static bool isATTrackingEnabled(ATTrackingManagerAuthorizationStatus status) {
    if (ATTrackingManagerAuthorizationStatusAuthorized == status) {
        return true;
    }
    return false;
}

- (void)helperRequestIDFAPermissionWithBlock:(IDFARequestBlock) complete {
    if (@available(iOS 14, *)) {
        ATTrackingManagerAuthorizationStatus authStatus = ATTrackingManager.trackingAuthorizationStatus;
        if (ATTrackingManagerAuthorizationStatusNotDetermined == authStatus) {
            [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
                if (nil != complete) {
                    return complete(isATTrackingEnabled(status));
                }
            }];
        } else if (nil != complete) {
            return complete(isATTrackingEnabled(authStatus));
        }
    }
}

- (void)initFaceGuardDevice {
    FaceGuardDevice * faceGuardDevice = [FaceGuardDevice sharedInstance];
    NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
    [options setValue:@"0" forKey:@"IPv6"]; // 设置IPv4
    if (nil != faceGuardDevice) {
        [faceGuardDevice initFG:@"123e4567e89b12d3a45642661417****" withOptions:options callback:^ (int code) {
            NSString * initResult = [NSString stringWithFormat: @ "人脸保镖初始化，结果 %d", code];
            NSLog(@ "%@", initResult);

            if (10000 != code) {
                NSLog(@ "初始化失败，后续getDeviceToken接口调用结果不可用于风险标签查询");
            } else {
                NSLog(@ "初始化成功，后续可以正常调用getDeviceToken接口");
            }
        }];
    }
}

- (void)viewDidLoad {
    [super viewDidLoad];

    // iOS 14及以上系统需要用户弹框获取 IDFA 权限。
    if (@available(iOS 14, *)) {
        [self helperRequestIDFAPermissionWithBlock:^(bool success) {
            if (success) {
                NSLog(@"IDFA Permission OK.");
            } else {
                NSLog(@"No IDFA Permission.");
            }

            [self initFaceGuardDevice];
        }];
    } else {
        [self initFaceGuardDevice];
    }
}

参数说明：

userAppKey：用于标识用户身份，阿里云分配的AppKey，请联系商务经理获取。
重要
人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。
options：信息采集可选项，默认可以为null。可选参数如下：
字段名
说明
示例
IPv6
是否使用IPv6域名上报设备信息。
0（默认）：使用IPv4域名。
1：使用IPv6域名。
1
initCallback：初始化回调监听接口，可在回调中判断初始化是否成功, 默认可以为nil。其中，code 字段取值范围可参考code返回值。
说明
当 initCallback 回调的 code 值返回不为 10000 时，可以在 App 后续的逻辑中重新调用 initFG 接口进行数据采集，直到成功为止。

获取客户端Token（getDeviceToken）

获取客户端 token，并上报到业务自己的服务器，后续通过服务器端查询阿里云人脸保镖接口（DescribeFaceGuardRisk），从而获取客户端设备风险识别信息。

重要

获取人脸保镖Token，请注意此接口应该在收到初始化接口（initFG）回调成功（code==10000）之后调用，一般initFG接口会在3秒内完成。
建议 initFG 接口和 getDeviceToken 接口调用时间间隔2秒以上。
调用 getDeviceToken 时建议传入 bizId，可以将本次 token 和业务唯一认证 ID 绑定，后在服务端查询结果时将ID一起传入，可进行防止Token被篡改的校验。

函数原型：

@interface FaceGuardDevice : NSObject
- (FaceGuardToken *) getDeviceToken;
  // 推荐传入bizID。
- (FaceGuardToken *) getDeviceToken:(NSString *)bizID;
@end

调用示例

// 推荐传入bizID，防止deviceToken被篡改。
NSString *bizID = @"1234567890abcdef1234567890ab****";
FaceGuardToken *faceGuardToken = [faceGuardDevice getDeviceToken:bizID];

NSString *rs = [NSString stringWithFormat: @ "[%d]%@", faceGuardToken.code, faceGuardToken.token];
NSLog(@ "Token=>%@", rs);
if (10000 != faceGuardToken.code) {
    NSLog(@ "获取token失败，调用结果不可用于风险标签查询");
} else {
    NSLog(@ "获取token成功，后续可以正常查询风险标签");
}

参数：

bizID：客户的业务ID，可用于关联业务ID和token。默认情况可以不传。

返回值：

FaceGuardToken 类型，定义如下：

@interface FaceGuardToken: NSObject

/**
 * 获取token操作的结果
 */
@property(atomic) int code;

/**
 * 包含token结果的字符串
 */
@property(copy, atomic) NSString * token;
@end

code：返回接口调用状态码，可用于判断接口调用是否成功。

code返回值

Code	说明
10000	SDK 采集数据成功。
10001	SDK 未采集数据。
10002	SDK 需要的基础权限未完全授权。
10003	系统未知错误。
10004	网络错误。
10005	网络错误，返回内容为空串。
10006	网络返回的格式非法。
10007	服务端配置解析失败。
10008	内部采集数据未完成。
10009	AppKey为空。
10010	其他参数错误。

token：返回 token 字符串信息，可用于业务后续查询阿里云人脸保镖接口。
重要
token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右。
如果业务上出现了大量的长 token，首先请确保客户端的网络是畅通的；其次，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

携带Token请求服务端

成功获取deviceToken（FaceGuardDevice.token）后，可携带此参数请求业务服务器，由服务端查询并校验结果。具体操作，请参见服务端API接口。