设备风险SDK Android接入

本文档介绍了设备风险SDK(Android系统)的接入流程。

前提条件

    设备风险SDK需在Android 4.0.3+(minSdkVersion版本15+)以上版本的系统运行。

合规指南

1、您需要确保App有《隐私政策》,并且在用户首次启动App时就弹出《隐私政策》取得用户同意,请勿默认客户已勾选。

2、您务必在《隐私政策》中向用户告知使用阿里云设备风险识别SDK,参考条款如下:

  • 使用SDK名称:阿里云设备风险识别SDK; 

  • 服务类型:检测篡改设备、模拟器、恶意脚本等异常设备 ;

  • 收集设备信息类型:设备型号、操作系统版本、设备设置、MAC地址、设备识别符(IMEI、IDFA、Android ID、IMSI等)、设备环境等软件特征信息;

3、您务必确保用户同意《隐私政策》之后,再初始化阿里云设备风险识别SDK。

权限说明

为增强风险识别效果,当前SDK需要以下权限:

权限内容

是否必选

备注

android.permission.INTERNET

没有该权限将导致SDK功能不可用。

android.permission.ACCESS_NETWORK_STATE

否(推荐赋予)

用于获取设备网络状态信息。

android.permission.READ_PHONE_STATE

否(推荐赋予)

该部分权限在Android 6.0以上系统中需要动态获取。

如果您要启用相关权限,那么在接入设备风险SDK并调用init初始化接口之前,确保您的App已经被授予了相关权限。

android.permission.WRITE_EXTERNAL_STORAGE

否(推荐赋予)

android.permission.READ_EXTERNAL_STORAGE

否(推荐赋予)

下载和配置SDK

  1. 下载Android SDK,并完成解压。SDK为Android标准的.aar包。

  2. 拷贝SDK的aar文件到工程的libs目录下,并在APP的build.gradle中添加以下依赖关系:

// 设备风险识别SDK
implementation files('libs/Android-AliyunDevice-版本号.aar')

// 三方网络库依赖
implementation 'com.squareup.okhttp3:okhttp:3.11.0'
implementation 'com.squareup.okio:okio:1.14.0

注意:三方网络库不能省略,否则会造成设备风险识别SDK无法联网。

初始化SDK

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

  • 函数原型

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

public void init(Context ctx, 
                 String appKey, 
                 SecurityInitListener securityInitListener);
  • 参数

ctx:当前Application Context,或Activity Context。

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

securityInitListener:设备风险SDK初始化回调接口,可在回调中判断初始化是否成功。其中,code字段取值范围可参考“状态返回值”。

  • 返回值

无。

获取Session

获取客户端Session,并上报到业务服务器,后续通过服务器端查询阿里云设备风险识别接口,从而获取设备风险信息。

  • 函数原型

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

public SecuritySession getSession();
  • 返回值

SecuritySession类型。

code:返回接口调用状态码,可用于判断接口调用是否成功。code字段取值范围可参考“状态返回值”。

session:返回Session字符串信息,可用于业务后续查询阿里云设备风险识别接口。

注意(非常重要):

1. getSession接口相对比较耗时,请务必在APP非主线程上调用,否则可能会引起ANR而导致APP Crash。

2. 因为数据上报可能存在延迟,请确保SDK的init接口和getSession接口调用时间能间隔2秒以上。

3. Session字符串在网络环境良好的场景下,长度为600字节左右;在网络环境较差的场景下,返回的长度在2.5K左右。

状态返回值

SecurityCode

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

其他参数错误

示例代码

初始化设备风险SDK,init接口需要在APP启动尽可能早的时候调用。

其中,参数ALIYUN_APPKEY用于标识用户身份,可在阿里云控制台的设备APP管理申请获取。

public class CustomApplication extends Application {
    private static String ALIYUN_APPKEY = "xxxx";

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

        // 初始化设备风险SDK,init接口需要在APP启动尽可能早的时候调用。
        SecurityDevice.getInstance().init(this, ALIYUN_APPKEY, null);
    }
}

在业务需要风险识别的场景下(如注册、活动推广等)获取户端Session并上报到业务的服务器端。确保init和getSession接口的调用间隔在2秒以上。

另外,getSession接口比较耗时,切勿在UI线程中调用。

new Thread() {
    @Override
    public void run() {
        SecuritySession securitySession = SecurityDevice.getInstance().getSession();
        if(null != securitySession){
            if(SecurityCode.SC_SUCCESS == securitySession.code){
                Log.d("AliyunDevice", "session: " + securitySession.session);

                // 发送session到业务自有服务器并查询阿里云设备风险识别接口。
                // sendToAPPServer(securitySession.session);
            } else {
                Log.e("AliyunDevice", "getSession error, code: " + securitySession.code);
            }
        } else {
            Log.e("AliyunDevice", "getSession is null.");
        }
    }
}.start();

接口混淆配置

-keep class net.security.device.api.** {*;}
-dontwarn net.security.device.api.**

调用风险识别API接口

将deviceToken与其他参数,根据如下相应的风险识别服务事件参数文档说明,请求风险识别API接口进行识别:

注册风险识别功能及参数说明

营销风险识别功能及参数说明

登录风险识别功能及参数说明

设备风险识别事件及返回参数

接入和使用时序图如下,其中第1和2步骤仅首次加载需要调用,第3、4、5、6、7、8、9步骤可以根据业务情况循环发起。

调用风险识别API流程

常见问题答疑

1. 设备风险识别SDK支付哪些架构?

目前支持arm、armv7和arm64三个架构。

2. SDK的大小是多少?

单架构的SO文件在1.8M左右。

设备风险识别SDK为了保证自身的抗逆向性以及数据在网络传输过程中的安全性,SDK中有大量的插花、膨胀及加解密操作,所以SDK体积会相对较大。

3. 为什么获取的session这么长?

正常情况下Session的长度在600字节左右,2.5K以上的长Session只会出现在网络较差的场景下。

如果业务上出现了大量的长Session,首先请确保客户端的网络是畅通的;其次,请确保SDK的init接口和getSession接口调用能间隔2秒以上。