Android接入

1. 初始化（initWithOptions）

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

• 函数原型

  public void initWithOptions(Context ctx, 
                         String userAppKey,
                         Map<String, String> options,
                         FaceSecInitListener securityInitListener);

• 调用示例

  public class CustomApplication extends Application {
      private static String ALIYUN_APPKEY = "123e4567e89b12d3a45642661417****";
      @Override
      public void onCreate() {
          super.onCreate();
          // 初始化人脸保镖SDK，initWithOptions接口需要在APP启动尽可能早的时候调用。
          Map<String, String> options = new HashMap<>();
          options.put("IPv6", "0"); // 设置为IPv4
          options.put("DataSwitch", "0"); // 设置为初始化阶段采集
          FaceSecDevice.getInstance().initWithOptions(this, ALIYUN_APPKEY, options, null);
      }
  }

• 参数说明

  • ctx：当前 Application Context，或 Activity Context。

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

    重要

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

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

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

  • securityInitListener：初始化回调监听接口，可在回调中判断初始化是否成功， 默认可以传入null。

    securityInitListener定义

    public interface FaceSecInitListener {
        // code表示接口调用状态码
        void onInitFinish(int code);
    }

    code 字段取值范围可参考code返回值。

2. 获取客户端Token（getDeviceToken）

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

• 调用示例

  new Thread() {
      @Override
      public void run() {
          // 推荐传入bizId，防止deviceToken被篡改。
          String bizId = "1234567890abcdef1234567890ab****";
          FaceSecToken deviceToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
          if(null != deviceToken){
              if(FaceSecCode.SC_SUCCESS == deviceToken.code){
                  Log.d("AliyunFace", "token: " + deviceToken.token);
              } else {
                  Log.e("AliyunFace", "getDeviceToken error, code: " + deviceToken.code);
              }
          } else {
              Log.e("AliyunFace", "getDeviceToken is null.");
          }
      }
  }.start();

• 参数

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

• 返回值

  • FaceSecToken 类型，定义如下：

    public class FaceSecToken {
        // 接口调用状态码
        public int code;
        
        // 用于服务器端查询结果的token字符串。
        public String token;
    }

  • 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 字符串信息，可用于业务后续查询阿里云人脸保镖接口。

    重要

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

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

3. 携带Token请求服务端

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