设备风险 SDK Android 接入

1. 初始化（initWithOptions）

该函数用于完成信息采集。在进行风险识别时，需要在满足合规要求的情况下尽可能早地调用。

• 函数原型

  public interface SecurityInitListener {
      // code 表示接口调用状态码
      void onInitFinish(int code);
  }
  public void initWithOptions(Context ctx,
                   String appKey,
                  Map<String, String> options,
                   SecurityInitListener securityInitListener);

• 参数说明

  ctx：当前 Application Context，或 Activity Context。

  appKey：用于标识用户身份，可在阿里云控制台的设备 App 管理申请获取。

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

  字段名	说明	示例
  IPv6	是否使用 IPv6 域名上报设备信息。 0（默认）：使用 IPv4 域名。 1：使用 IPv6 域名。	"1"
  CustomUrl	设置数据上报服务器域名	"https://cloudauth-device.aliyuncs.com"
  CustomHost	设置数据上报服务器 host	"cloudauth-device.aliyuncs.com"
  DataType	设置不采集敏感数据的类型。 默认为空：采集所有数据； 具体可配置数据如下表。	单选： NO_UNIQUE_DEVICE_DATA 多选： NO_UNIQUE_DEVICE_DATA | NO_IDENTIFY_DEVICE_DATA

  敏感数据的类型	说明	设备信息字段详情
  NO_UNIQUE_DEVICE_DATA	可变更唯一设备标识码	包括：OAID、Google 广告 ID、Android ID。
  NO_IDENTIFY_DEVICE_DATA	不可变更唯一设备标识码	包括：IMEI、IMSI、SimSerial、BuildSerial（SN）、MAC 地址。
  NO_BASIC_DEVICE_DATA	基础标识信息	包括：设备名（Build.DEVICE）、Android 版本号（Build.VERSION#RELEASE）、屏幕分辨率。
  NO_EXTRA_DEVICE_DATA	扩展敏感信息	包括：黑灰产 App 列表、局域网 IP、DNS IP、连接的 WIFI 信息（SSID、BSSID）、附近 WIFI 列表、定位信息。

  说明

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

  endpoints 默认服务地址：

  • 国内（默认）地址：https://cloudauth-device.aliyuncs.com

  securityInitListener：初始化回调监听接口，可在回调中判断初始化是否成功，默认可以传入 null。其中，code 字段取值范围可参考状态返回值。

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

• 调用示例

  public class CustomApplication extends Application {
      private static String USER_PRODUCT_KEY = "123e4567e89b12d3a45642661417****";
  
      @Override
      public void onCreate() {
          super.onCreate();
  
          Map<String, String> options = new HashMap<>();
          options.put("IPv6", "0"); // 设置为 IPv4
          //增加隐私数据采集开关，多选使用｜进行或运算，再转成字符串。
          //options.put("DataType",  String.valueOf(NO_UNIQUE_DEVICE_DATA | NO_IDENTIFY_DEVICE_DATA));
          // 设置自定义的数据上报地域
          // options.put("CustomUrl", "xxx"); 设置上报站点 Url
          // options.put("CustomHost", "xxx"); 设置上报站点 Host
  
          // 标准调用(推荐)
          SecurityDevice.getInstance().initWithOptions(this, USER_PRODUCT_KEY,
                                                      options, null);
  
          // 回调调用
          SecurityDevice.getInstance().initWithOptions(this, USER_PRODUCT_KEY,
                                        options, new SecurityInitListener() {
                @Override
                public void onInitFinish(int code) {
                    if (SecurityCode.SC_SUCCESS != code) {
                        Log.d("AliyunDeviceRisk", "初始化失败");
                    } else {
                        Log.d("AliyunDeviceRisk", "初始化成功");
                    }
                }
            });
      }
  }

2. 获取客户端 Token（getDeviceToken）

获取客户端 token 并上报到业务服务器，后续通过服务器端设备风险识别API获取设备风险信息。

• 函数原型

  public SecurityToken getDeviceToken();
  // 推荐传入 bizId
  public SecurityToken getDeviceToken(String bizId)

• 参数

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

• 返回值

  SecurityToken 类型，定义如下：

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

  • code：返回接口调用状态码，可用于判断接口调用是否成功。code 字段取值范围可参考状态返回值。

  • token：返回 token 字符串信息，可用于业务后续查询阿里云设备风险识别接口。

    重要

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

    • 国内：有网"Tkxxxx"、弱网"UFxxxx"；

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

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

    • 其次，确保 SDK 的initWithOptions接口和getDeviceToken接口调用。

• 调用示例

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

3. 携带 Token 请求服务端

成功获取 deviceToken 后，将 deviceToken 作为参数传至您的业务服务端。由服务端调用阿里云设备风险识别 API 接口，传入 deviceToken 查询并校验设备风险信息。