设备风险 SDK Android 接入

1. 初始化（initWithOptions）

该函数用于完成 SDK 初始化和信息采集。在进行风险识别时，需要在满足合规要求的情况下尽可能早地调用。该函数在一次 APP 启动后只需要调用一次。

• 函数原型

    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 域名。	"0"
    CustomUrl	设置数据上报服务器域名。指定站点上报时使用，默认不需要设置。	"https://cloudauth-device.aliyuncs.com"
    CustomHost	设置数据上报服务器 host。需与 CustomUrl 配对使用，默认和 CustomUrl 一起不需要设置。	"cloudauth-device.aliyuncs.com"
    DataType	设置不采集设备数据的类型。默认为空（推荐），采集所有数据，具体可配置数据如下表。	单选：NO_UNIQUE_DEVICE_DATA多选：NO_UNIQUE_DEVICE_DATA｜NO_IDENTIFY_DEVICE_DATA

    DataType参数说明

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

    CustomUrl和CustomHost参数说明

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

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

• 调用示例

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();
// 推荐传入，可用于关联业务ID和deviceToken
public SecurityToken getDeviceToken(String bizId)

public class SecurityToken {
    // 接口调用状态码
    public int code;

    // 用于服务器端查询结果的 token 字符串。
    public String 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 查询并校验设备风险信息。