iOS接入

1. 初始化（initFG）

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

• 函数原型

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

• 调用示例

  - (void)initFaceGuardDevice {
      FaceGuardDevice *faceGuardDevice = [FaceGuardDevice sharedInstance];
      NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
      [options setValue:@"0" forKey:@"IPv6"]; // 设置IPv4
      [options setValue:@"0" forKey:@"DataSwitch"]; // 设置设备信息采集上报时机
      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];
          
      [self initFaceGuardDevice];
  }

• 参数说明

  • userAppKey：用于标识用户身份，阿里云分配的AppKey，请联系商务经理获取。

    重要

    人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。

  • options：信息采集可选项，默认可以为null。可选参数如下：

    字段名	说明	示例
    IPv6	是否使用IPv6域名上报设备信息： "0"（默认）：否（使用IPv4域名） "1"：是（使用IPv6域名）	"1"
    DataSwitch	是否获取Token时上报设备信息： "0"（默认）：否（初始化时上报） "1"：是（获取Token时上报） 说明 建议采用默认配置。	"1"

  • initCallback：初始化回调监听接口，可在回调中判断初始化是否成功，默认可以为nil。其中，code 字段取值范围可参考code返回值。

    说明

    当 initCallback 回调的 code 值返回不为 10000 时，可以在 App 后续的逻辑中重新调用 initFG 接口进行数据采集，直到成功为止。

2. 获取客户端Token（getDeviceToken）

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

• 函数原型

  @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	其他参数错误。
    10011	密钥计算错误
    10012	APPKey 无效

  • token：返回 token 字符串信息，可用于业务后续查询阿里云人脸保镖接口。

    重要

    token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右。

    如果业务上出现了大量的长 token，首先请确保客户端的网络是畅通的；其次，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

3. 携带Token请求服务端

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