KiwiGuard SDK (Android)下载与接入文档

1.最新更新内容

更新版本：

上线KiwiGuard Android监测v1.8（SaaS平台侧）

上线KiwiGuard Android SDK v3.2.11（本页面第2节中可下载）

更新时间：

2021/9/16 12:00:00

更新内容：

① 优化了SaaS平台侧：KiwiGuard Android SDK的接入流程；

② 优化了SaaS平台侧：终端威胁异常的数据展示；

③ 优化了后端接入时：HTTP API的响应数据**（API升级至v2版本），旨在为企业提供可靠且全面的终端威胁数据源（为了更好的体验，请尽量使用v2版本的API，见5.2.1）**，

④ KiwiGuard Android SDK v3.2.11版本支持ameabi架构；

⑤ 修复了一些已知问题。

2 KiwiGuard SDK下载

**版本号：**KiwiGuard Android-v3.2.11（若无特殊要求，请下载集成最新SDK）

**发布时间：**2021/9/16 11:00:00

**版本描述：**① 优化了数据交互，旨在为企业提供可靠且全面的终端威胁数据源；② 支持ameabi架构

**版本号：**KiwiGuard Android-v3.2.10

**发布时间：**2021/7/21 18:00:00

**版本描述：**虚拟机环境监测，新增对51虚拟机和光速虚拟机的检测支持

**版本号：**KiwiGuard Android-v3.2.9

**发布时间：**2021/7/1 19:00:00

**版本描述：**修复虚拟机检测漏报VMOS pro bug ，修复其他已知bug

3 名称解释

4 法规要求

您应向您的终端用户逐一明示您嵌入的第三方SDK收集使用个人信息的目的、方式和范围。

您应当在《隐私政策》中明确告知终端用户，您选择了成都盈海益讯科技有限公司作为合作方，并委托其收集、使用、加工和处理终端用户个人信息。成都盈海益讯科技有限公司建议您在《隐私政策》中的“我们如何共享、转让、公开披露您的个人信息”的表述条款中增加如下内容（关于个人信息共享给第三方说明的部分，强烈建议此部分由您专业的法务团队优化完善，详情可参考《KiwiGuard SDK隐私政策》）：

为了识别客户端或终端用户的异常状态，为了对盗版应用、虚假设备、游戏外挂、环境风险、对抗事件等威胁场景进行监测与管控，我们的产品会集成第三方的SDK或类似应用程序，具体如下：

5 KiwiGuard SDK手动接入流程

5.1 KiwiGuard SDK前端接入

集成KiwiGuard SDK之前：请先在几维安全《移动应用安全管理平台》创建应用组、创建App，获取appID。

5.1.1 集成KiwiGuard SDK

（1）下载KiwiGuard SDK

下载KiwiGuard SDK，下载之后得到一个KiwiGuard-SDK-v3.x.y.zip 的一个文件，解压后文件中包含.aar 和 .lic两个文件。

（2）Android Studio 集成

① 把kiwiguard.aar放到相应模块的libs目录下；

② 把kiwiguard.lic放到相应模块的assets目录下；

③ 在该模块的build.gradle中如下配置；

android {
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
    repositories{
        flatDir{
            dirs 'libs'
        }
    }
}
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation files('libs/kiwiguard.aar')
}

（3）添加SDK所需权限

编辑AndroidManifest.xml 文件，添加如下权限。

<!-- 网络权限(必选) -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- IMEI获取(必选) -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

（4）Proguard混淆配置

编辑Proguard 配置文件，所在位置一般为 app/src/proguard-rules.pro。

-dontwarn com.kiwisec.**
-keep class com.kiwisec.**{*;}

（5）API 6.0或以上动态权限申请说明

Android 6.0 及以上对于敏感权限需要弹窗申请，所以上面所需权限中的READ_PHONE_STATE 需要动态申请，申请时可按如下示例进行。

public void requestPermission() {
        //权限检查
        if (ContextCompat.checkSelfPermission(this,
                Manifest.permission.READ_PHONE_STATE
) != PackageManager.PERMISSION_GRANTED) {
            //申请权限
            ActivityCompat.requestPermissions(this,
                    new String[]{Manifest.permission.READ_PHONE_STATE
}, 1);
        }
    }

5.1.2 接口使用说明

（1）初始化SDK( 该步骤不可省略，setAppID()、setup() 都必须调用 )

初始化建议放到应用Application中的onCreate( ) 方法中进行。

import com.kiwisec.KiwiGuard;

public class MyApplication extends Application
{
    @Override
    public void onCreate()
    {
        super.onCreate();

        // 设置KiwiGuard 必要的项目关联信息
        // 在调用SDK 之前需要调用该接口设置appID

        // @param appID - 从几维平台创建项目时获取
        // @throws RuntimeException - appID为空或者空字串则抛出异常
        KiwiGuard.setAppID("在平台创建KiwiGuard手动SDK项目的AppID");

        // 初始化KiwiGuard
        // 初始化 KiwiGuard SDK
        KiwiGuard.setup();
    }
}

（2）获取deviceToken

整个过程由于是耗时操作，必须要在非主线程上执行，否则会crash。

 private void requestDeviceToken(){
        Thread thread = new Thread(new Runnable() {
            @Override
            public void run() {
                HashMap<String,String> options = new HashMap<>();
                String deviceToken = KiwiGuard.getDeviceToken(options);
                //TODO: 把 deviceToken 结合其他参数,发送POST请求,可以获取设备风险信息 (参考KiwiGuard HTTP接口接入)
            }
        });
        thread.start();
    }

在需要进行风险识别时调用上述的getDeviceToken，例如：

• 新用户注册后，进行风险画像查询，用于新人红包、注册礼物等的差异化投放；
• 存量用户登录后，进行风险画像查询，用于日常活动运营的差异化投放；
• 活动奖励下发前，进行风险画像查询，例如随机红包、抽奖等概率性活动；
• 每日的例行查询，进行画像库或风控引擎的数据更新。 （3）异常说明

  调用 setAppID()时，appID 设置不正确 
  RuntimeException("appID can't be null or empty!");
  调用 setup() 前，未调用setAppID()
  RuntimeException("You need call KiwiGuard.setAppID() before setup KiwiGuard SDK");
  调用 getDeviceToken()时，未开子线程调用
  RuntimeException("Can't call KiwiGuard.getToken in MainUI thread");
  ----------- native 层会抛出以下两个异常 ----------
  初始化SDK时，appID 未设置
  NullPointerException("options can't be null!");
  初始化SDK时，未获取到appID 
  RuntimeException("fetch appID exception!");
  

5.2 KiwiGuard SDK后端接入

备注：本节可通过访问几维安全服务端API获取终端威胁数据源；可在App测试环节与上线后进行操作。

5.2.1 HTTP接口接入方法

（1） 接口地址（v2）

encrypt_key = 'secret:{AppGroupSecret}*{deviceToken}*{timestamp}:encrypt'.format(AppGroupSecret=AppGroupSecret, deviceToken=deviceToken, timestamp=timestamp)

备注：2021/9/16 11:00:00已将API升级至v2版本，旨在为企业提供可靠且全面的终端威胁数据源**（为了更好的体验，请尽量使用v2版本的API）**，点击查看v1版本API地址及响应的数据

（2） 请求参数

*如何生成参数sign？

【Python实例】

① 构建待加密的指定规则字符串 ；

AppGroupSecret： 几维安全SaaS平台获取( KiwiGuard > 应用管理 > 应用组AppGroupSecret )

encrypt_key = 'secret:{AppGroupSecret}*{deviceToken}*{timestamp}:encrypt'.format(AppGroupSecret=AppGroupSecret, deviceToken=deviceToken, timestamp=timestamp)

② 使用md5加密，获取加密后的数据传递给sign字段；

import hashlib
m = hashlib.md5()
m.update(encrypt_key.encode())
sign = m.hexdigest()

【Java实例】

// 封装的计算sign函数    
public String getStrArrMd5Sign(String []strArr){
        StringBuilder sb = new StringBuilder();
        String signStr = null, signMd5 = null;
        if(strArr != null && strArr.length > 0){
            sb.append("secret:");
            for(int i=0; i<strArr.length; i++){
                sb.append(strArr[i]);
                if(i != (strArr.length-1))
                    sb.append("*");
            }
            sb.append(":encrypt");
            signStr = sb.toString();
            Log.d(TAG,signStr);
            if(!signStr.isEmpty()){
                MessageDigest md = null;
                try{
                    md = MessageDigest.getInstance("MD5");
                    // 计算md5函数
                    md.update(signStr.getBytes());


                    signMd5 = new BigInteger(1, md.digest()).toString(16);
                                        // (fix)不满32位前面添加0
                    while(signMd5.length() < 32 ){
                        signMd5 = "0" + signMd5;
                    }
                }catch (Exception e){
                    Log.d(TAG,"no such MD5 algorithm"+e.getMessage());
                }
            }
        }

        return signMd5;
    }
// 调用上面封装的函数获取sign 
String sign = getStrArrMd5Sign(new String[]{AppGroupSecret
,deviceToken,"时间戳"});//请严格按照该拼接顺序(时间戳例如:"16509345787")

// 封装json 请求体
// appGroupID 和 appID 至少任意填一个
JSONObject jsonBody = new JSONObject();
                    jsonBody.put("deviceToken",deviceToken);
                    jsonBody.put("appGroupID","");
                    jsonBody.put("sign",sign);
                    jsonBody.put("timestamp","时间戳");
                    jsonBody.put("appID","");

// TODO 发起网络请求

*如何发送POST请求？

【Java实例】

public class HttpUtils {
    private static final MediaType JSON = MediaType.parse("application/json; charset=utf-8");
    private static OkHttpClient client = new OkHttpClient();

    public static Response post(String url, String json) throws IOException {
        RequestBody body = RequestBody.create(JSON, json);
        Request request = new Request.Builder()
                .url(url)      //填写接口地址
                .post(body)    //填写请求参数
                .build();
        Response response = client.newCall(request).execute();
        return response;
    }
}

【Python实例】

import hashlib, requests, pprint, json


def md5_convert(string):
    """
    计算字符串md5值
    :param string: 输入字符串
    :return: 字符串md5
    """
    m = hashlib.md5()
    m.update(string.encode())
    return m.hexdigest()

if __name__ == '__main__':
    appSecretKey = '****'  # 应用管理应用组所对应的 SecretKey
    deviceToken = '****'  # deviceID
    ts = ****  # 时间戳

    md5_key = 'secret:{appSecretKey}*{deviceToken}*{ts}:encrypt'.format(appSecretKey=appSecretKey, deviceToken=deviceToken, ts=ts)
    sign = md5_convert(md5_key)

    body = {
        "appGroupID": "****",  # 应用组id
，web端获取
        "appID": "****",  # appID，web端获取
        "deviceToken": deviceToken,
        "sign": sign,
        "timestamp": ts
    }

    pprint.pprint(json.loads(requests.post(url='****', json=body).text), depth=4)

（备注：若没有查看appGroupSecret的权限，请联系几维安全工作人员。）

（3）成功响应

成功示例：

{
    "message": "success!",
    "code": 1,
    "data": {
            "deviceID":"xxx",
            "fakeRiskDevice":{        
                "virtualEnv":{               
                key1:value1,
                key2:value2
            }
            },
            "environmentRiskDevice":{
                "root":{
                key1:value1
            }       
            },
            "fightRiskDevice":{
                "debug":{
                key1:value1
            }
            },
            "suspiciousRiskDevice":{
                "gameScriptTools": {
                key1:value1,
                key2:value2
            } 
            }
        }
}

（4）错误响应

失败示例：

{
    "message": '缺少查询参数！', 
    "code": 1880001
}

5.2.2 HTTP接口返回参数明细说明

成功响应时候，data字段Json类型的内容为：

（1）fakeRiskDevice详细内容

① 模拟器检测：

emulator详细内容：

② 虚拟机检测：

virtualEnv详细内容：

③ 云真机检测：

cloudMachine详细内容：

（2）environmentRiskDevice详细内容

① ROOT检测

ROOT环境详细内容：

② VPN检测

VPN详细内容：

（3）fightRiskDevice详细内容

debug详细内容：

（4）suspiciousRiskDevice详细内容

① GG修改器检测

gameGuard详细内容：

② 八门神器检测

xdGame详细内容：

③ SIM卡状态检测

SIM详细内容：

④ 调试模式检测

debugMode详细内容：

⑤ 自动点击工具检测

automaticTools详情内容：

⑥ 辅助服务检测

accessibilityService详细内容：

⑦ 多开工具检测

multipleTools详细内容：

⑧ Hook检测

hookDevice详细内容：

⑨ 工程模式检测

engineeringMode详细内容：

⑩ 远程操作工具检测

controlTools详细内容：

⑪ 云设备控制工具检测

cloudDeviceControlTools详细内容：

⑫ 程序脚本辅助工具检测

gameScriptTools详细内容：

6 FAQ

6.1 Cleartext HTTP traffic to xxx.xxx.xxx.xxx not permitted

这个问题一般是apk 中使用了http 通信，高版本手机中默认只允许https 通信。所以如果要使用http通信，需要在AndroidManifest.xml 中添加一行配置：

android:usesCleartextTraffic="true"

在AndroidManifest.xml 中如下：

<application
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:name=".MyApplication"

android:usesCleartextTraffic="true"
android:theme="@style/AppTheme">