ID Verification：iOS接入

1. 初始化（initFG）

SDK 内部初始化，在 App 启动的时候，您需要尽可能早地调用该函数。请参考接入流程，调用初始化 initFG 接口。

• 函数原型

  @interface FaceGuardDevice : NSObject
  
  /**
   *  DEVICE GUARD初始化函数
   */
  - (void)initFG:(NSString *)userProductKey 
          withOptions:(NSMutableDictionary *)options
          callback:(void (^)(int))initCallback;
  // ...
  @end

• 参数说明

  • userProductKey：用于标识用户身份，阿里云分配的产品 AppKey（不同于AK），请联系商务经理获取。

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

    说明

    常见国际站点不需要设置CustomUrl和CustomHost参数，默认使用新加坡站点。

    指定站点上报，需要设置CustomUrl和CustomHost为指定地域。

    字段名	说明	示例
    IPv6	是否使用IPv6域名上报设备信息。 0（默认）：使用IPv4域名 1：使用IPv6域名	"1"
    DataSwitch	设备信息上报时机。 0（默认）：初始化时 1：获取Token时 说明 建议采用默认配置。	"1"
    CustomUrl	设置数据上报服务器域名。	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
    CustomHost	设置数据上报服务器host。	"cloudauth-device.ap-southeast-1.aliyuncs.com"

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

• 调用示例

  NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
  [options setValue:@"0" forKey:@"IPv6"];       // 设置IPv4
  [options setValue:@"0" forKey:@"DataSwitch"]; // 设置为初始化阶段采集
  // 设置自定义的数据上报地域
  // [options setValue:@"xxx" forKey:@"CustomUrl"];  设置上报站点Url
  // [options setValue:@"xxx" forKey:@"CustomHost"]; 设置上报站点Host
  
  // 标准调用(推荐)
  [[FaceGuardDevice sharedInstance] initFG:@"******" withOptions:options callback:nil];
  
  // 回调调用
  [[FaceGuardDevice sharedInstance] initFG:@"******" withOptions:options callback:^(int code) {
      NSString * initResult = [NSString stringWithFormat: @ "设备助手初始化，结果 %d", code];
      NSLog(@ "%@", initResult);
  
      if (SC_SUCCESS != code) {
          NSLog(@ "初始化失败");
      } else {
          NSLog(@ "初始化成功");
      }
  }];

2. 获取客户端token（getDeviceToken）

获取客户端 token，请参考接入流程进行调用，并上报到业务自己的服务器，后续通过服务器端查询ADD_VERIFY_PRO的服务端API接口，从而验证设备地址。

• 函数原型

  @interface FaceGuardDevice : NSObject
  - (FaceGuardToken *) getDeviceToken;
  @end

• 返回值

  • FaceGuardToken 类型，定义如下：

    @interface FaceGuardToken: NSObject
    
    /**
     * 获取token操作的结果
     */
    @property(atomic) int code;
    
    /**
     * 包含token结果的字符串
     */
    @property(copy, atomic) NSString * token;
    @end

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

    code返回值

    FaceSecCode	Code	备注
    SC_SUCCESS	10000	SDK初始化成功。
    SC_NOT_INIT	10001	SDK未初始化。
    SC_NOT_PERMISSION	10002	SDK需要的Android基础权限未完全授权。
    SC_UNKNOWN_ERROR	10003	系统未知错误。
    SC_NETWORK_ERROR	10004	网络错误。
    SC_NETWORK_ERROR_EMPTY	10005	网络错误，返回内容为空串。
    SC_NETWORK_ERROR_INVALID	10006	网络返回的格式非法。
    SC_PARSE_SRV_CFG_ERROR	10007	服务端配置解析失败。
    SC_NETWORK_RET_CODE_ERROR	10008	网关返回失败。
    SC_APPKEY_EMPTY	10009	AppKey为空。
    SC_PARAMS_ERROR	10010	其他参数错误。
    SC_FGKEY_ERROR	10011	密钥计算错误。
    SC_APPKEY_ERROR	10012	APPKey 无效。

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

    重要

    token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右，并且带有特殊标识：

    • 有网："U0dfTkxxxx"

    • 弱网："U0dfUFxxxx"

    如果业务上出现了大量的长 token：

    • 首先，请确保客户端的网络是畅通的；

    • 其次，请参考接入流程进行接入，确保 SDK 的 initFG 接口和 getDeviceToken 接口调用间隔在 3 秒以上。

• 调用示例

  // 推荐传入bizId,防止deviceToken被篡改
  NSString *bizId = @"1234567890abcdef******";
  FaceGuardToken *deviceToken = [[FaceGuardDevice sharedInstance] getDeviceToken:bizId];
  
  if (deviceToken == nil || SC_SUCCESS != deviceToken.code) {
      NSLog(@"获取token失败, 调用结果不可用于风险标签查询");
  } else {
      NSLog(@"获取token成功, 后续可以正常查询风险标签. Token: %@", deviceToken.token);
  }

3. 携带Token请求服务端

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