设备风险 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。需与 CustomUrl 配对使用。	"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 字段取值范围可参考SDK Android 接入。

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

• 调用示例

public class CustomApplication extends Application {
    // 在阿里云控制台「设备App管理」中创建应用后获取
    private static String appKey = "<请在控制台创建应用后获取>";

    @Override
    public void onCreate() {
        super.onCreate();

        Map<String, String> options = new HashMap<>();
        options.put("IPv6", "0"); // 设置为IPv4，使用IPv6时改为"1"
        //增加隐私数据采集开关，多选使用｜进行或运算，再转成字符串。
        //options.put("DataType",  String.valueOf(NO_UNIQUE_DEVICE_DATA | NO_IDENTIFY_DEVICE_DATA));
        // 设置自定义的数据上报地域（默认不需要设置，仅指定站点时使用）
        // options.put("CustomUrl", "https://cloudauth-device.aliyuncs.com");
        // options.put("CustomHost", "cloudauth-device.aliyuncs.com");

        // 方式一：标准调用（推荐，不关心初始化结果时使用）
        SecurityDevice.getInstance().initWithOptions(this, appKey, options, null);

        // 方式二：回调调用（需要监听初始化结果时使用）
        SecurityDevice.getInstance().initWithOptions(this, appKey, options, new SecurityInitListener() {
              @Override
              public void onInitFinish(int code) {
                  if (SecurityCode.SC_SUCCESS != code) {
                      Log.d("AliyunDeviceRisk", "初始化失败！Code=" + code);
                  } 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 字段取值范围可参考SDK Android 接入。

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

• 调用示例

// 建议在非主线程调用，避免阻塞 UI 导致 ANR
new Thread() {
    @Override
    public void run() {
        // 推荐传入 bizId，将 token 与业务 ID 绑定。
        // 服务端查询时传入相同 bizId，可校验 token 是否被篡改。
        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 查询并校验设备风险信息。