iOS接入

1. 初始化（initFG）

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

• 函数原型

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

• 参数说明

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

    重要

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

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

    说明

    指定站点上报，需要设置CustomUrl和CustomHost为国内指定地域，默认情况不需要设置。

    字段名	说明	示例
    IPv6	是否使用IPv6域名上报设备信息： 0（默认）：否（使用IPv4域名） 1：是（使用IPv6域名）	"1"
    DataSwitch	设备信息上报时机。 0（默认）：初始化时 1：获取Token时 说明 建议采用默认配置。	"1"
    CustomUrl	设置数据上报服务器域名。	"https://cloudauth-device.aliyuncs.com"
    CustomHost	设置数据上报服务器host。	"cloudauth-device.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，请参考接入流程在[时机2]进行调用，并上报到业务自己的服务器，后续通过服务器端查询阿里云设备助手接口（DescribeFaceGuardRisk），从而获取客户端设备风险识别信息。

• 函数原型

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

• 参数

  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 秒以上。

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

    • 有网："Tkxxxx"

    • 弱网："UFxxxx"

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

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

    • 其次，请参考接入流程进行接入，在[时机1]调用初始化 initWithOptions 接口，在[时机2]调用 getDeviceToken 接口；或确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

• 调用示例

  // 推荐传入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接口。