设备风险 SDK Android 接入

1. AndroidManifest.xml 配置（可选）

<!--
    可选增强项：添加AppZygote进程与service服务可以提升风控检测能力。
    1、在已有的 <application> 标签上增加 android:zygotePreloadName 属性
    2、在 <application> 标签内增加一个 <service> 声明
-->
<application android:zygotePreloadName="net.security.device.api.compat.CompatPreloader"
  <service
    android:name="net.security.device.api.compat.CompatBridgeService"
    android:exported="false"
    android:isolatedProcess="true"
    android:useAppZygote="true" />
</application>

2. 初始化（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<>();
    // 隐私采集开关：默认无需配置；如需端上范围关闭，多选用 | 或运算后转字符串
    // 如果只需关闭某个采集字段，而不是通过DataType参数范围关闭，也可以联系我们通过服务端下发关闭。
    // 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", "初始化成功");
        }
      }
    });
  }
}

3. 获取客户端 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();

4. 携带 Token 请求服务端

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