隐私说明

请参照网易易盾隐私政策，请将易盾隐私政策链接放到应用“用户协议”中。

接入说明

接入“智能风控” SDK，开发者需要完成以下步骤：

1. 根据应用/游戏开发平台，将SDK拷贝到指定的工程目录，并修改项目配置；
2. 接入风控SDK必接接口，根据业务需求接入建议接口；
3. 测试风控SDK接入是否正确；
4. 验证风控SDK功能效果；
5. 按业务常规发版流程进行测试与发版

注意：

• 全局必须要接入的接口：初始化接口
• 用户登录后必须要接入的接口：设置用户信息接口
• 关键业务埋点时必须要使用的接口：同步获取凭证/异步获取凭证
• 强烈建议接入的接口：交互接口
• 建议接入的接口：心跳接口、安全通信协议接口

三、接入步骤

请登录易盾官网后台风控引擎-服务管理获取SDK，详情如图

导入插件

将插件文件夹粘贴到工程目录中（以htprotect_example为例）。 在项目根目录建立 plugins（可自定）文件夹，将plugin项目移至其中，移动后目录架构如下

打开项目的pubspec.yaml，在dev_dependencies中添加易盾 plugin 插件

更新依赖，在Flutter项目根目录下执行：Flutter pub get

若使用ProGuard进行混淆，需要将SDK使用的类排除掉。若使用Android Studio开发，则在proguard-rules.pro文件中添加如下信息：

 -keep class com.netease.htprotect.**{*;}
 -keep class com.netease.mobsec.**{*;}
 

### <a id="3.2">**SDK接口调用**</a>

（1）初始化

• 头文件

import 'package:htprotect/htprotect.dart';

• 初始化接口

_htprotectPlugin.init("易盾业务id", params: params).then((initResult) {
  var code = initResult['code'];
  if (code == 200) {
    Fluttertoast.showToast(
      msg: "Init successfully", gravity: ToastGravity.CENTER);
  } else {
    String Msg = initResult['Msg'];
    Fluttertoast.showToast(
      msg: 'init failed, Msg is: $Msg',
      gravity: ToastGravity.CENTER);
  }
});

部分产品相关参数请用账号登录易盾官网控制台获取参考

（2）登录接口

用户登录或者切换游戏账号的时候，调用以下接口

String businessId = "易盾提供的业务id";
String roleId = "testroleId";
String roleName = "testroleName";
String roleAccount = "testroleAccount";
String roleServer = "testroleServer";
int serverId = 123;
String gameJson = "{'gameVersion': 'ccc', 'assetVersion': 'ddd'}";

_htprotectPlugin.setRoleInfo(businessId, roleId, roleName, roleAccount, roleServer, serverId, gameJson).then((result) {
  Fluttertoast.showToast(
    msg: 'setRoleInfo, Msg is: $result',
    gravity: ToastGravity.CENTER);
});

3、验证SDK接入是否正确

1、确认客户端SDK相关接口已调用

2、运行程序，确保已触发相关接口。

3、前往官网查询数据；输入角色信息进行查询。

四、SDK 接入调用说明

1、SDK 初始化接口

接口用途：

用于初始化智能风控 SDK。

接入须知：

1. 使用其他接口之前，必须先调用初始化接口，建议在应用/游戏启动过后第一时间调用（初始化后，并不会获取任何个人隐私相关信息）；
2. 该接口为 必须调用接口。

函数原型：

Future<Map<dynamic, dynamic>> init(String productId,{Map<String, dynamic>? params})

参数说明：

参数	说明	必要性
productId	易盾HTP分配的productId，可登录易盾后台获取	必填
serverType	设置服务器归属地 ,智能风控默认上报的服务器为中国大陆的服务器，若需要更改服务器归属地，可以调用该接口进行配置，支持的类型如下： serverType = 1,中国大陆地区，默认为该值，无需设置 serverType = 2, 中国台湾地区 ; serverType = 3 海外地区	可选
channel	设置渠道信息，供用户传入该app的渠道信息（比如：App Store CN/App Store EU）	可选
extData	设置额外信息，在数据上报中包含的额外信息	可选
host	私有化的客户需要通过该接口设置服务器地址	可选

• 回调参数说明：

回调参数	类型	描述
code	int	初始化结果code码 200，初始化正常 199，说明初始化参数错误，如果productId不合法或者过期 400，请将 msg 发送到贵方服务端，由贵方服务端转发给易盾服务端，易盾服务端返回结果，再将结果通过ioctl接口(16) 反馈给反外挂sdk
msg	String	初始化结果详情

示例代码：

Map<String,dynamic> params = {};
params['serverType'] = 1;
params['channel'] = 'test';
params['gameKey'] = '8ef016947a1eeed4ac5b07c700e2b3f5';
var map1 = {'aa': 'aaa', 'bb': 'bbb'};
params['extData'] = map1;

_htprotectPlugin.init(productId, params: params).then((initResult) {
  var code = initResult['code'];
  String msg = initResult['msg'];
  Fluttertoast.showToast(
    msg: "Init code: $code msg: $msg", gravity: ToastGravity.CENTER);
});

2、设置用户信息接口

接口用途：

游戏类型应用，在进行数据采集的过程中，会将角色 ID，角色名称、用户/角色账号等设置在风控 SDK 采集的数据中一同上传，用于表示角色信息，以便对有恶意、风险行为的用户/角色进行相应的处置。

接口须知：

1. 须在 SDK 初始化且 用户同意隐私政策后才能调用该接口；
2. 凡事涉及到用户登录、或者切换角色的地方，均需要调用该接口设置或者更新用户/玩家信息；

函数原型：

Future<int> setRoleInfo(
      String businessId,
      String roleId,
      String roleName,
      String roleAccount,
      String roleServer,
      int serverId,
      String gameJson)

参数说明：

• 入参说明：

参数	说明	必要性
businessId	当前业务 ID	必填
roleId	用户/玩家的角色 ID；非游戏类型应用，roleId 可以与 roleAccount 相同	必填
roleName	用户/玩家的角色名称；非游戏类型应用，roleName 可以是当前用户昵称相同	可选，不需要可填null
roleAccount	用户/玩家的账号；如业务方同时接入易盾反垃圾，则此账号需要与反垃圾接入中的account一致	可选，不需要可填null
roleServer	用户/玩家的角色的服务器名称	可选，不需要可填null
serverId	用户/玩家的角色所属服务器的 ID	可选，不需要可填null
gameJson	游戏类型应用需要上传的信息，对应一个 json 字符串	可选，不需要可填null

gameJson 字段说明：

key 名称	key 类型	key 值	必要性	说明
游戏版本号	String	GameVersion	可选，不需要可填null	游戏版本号
资源文件版本	String	AssetVersion	可选，不需要可填null	游戏类型应用的资源文件版本号

• 回调参数说明：

返回 int 类型，可能出现的值如下：

值	说明
0	成功
201	未初始化
203	businessId 不合法

示例代码：

Future<void> setRoleInfo() async {
String businessId = "31c9823e57b3b789341db4812c562ef1";
String roleId = "testroleId";
String roleName = "testroleName";
String roleAccount = "testroleAccount";
String roleServer = "testroleServer";
int serverId = 123;
String gameJson = "{'gameVersion': 'ccc', 'assetVersion': 'ddd'}";

_htprotectPlugin.setRoleInfo(businessId, roleId, roleName, roleAccount, roleServer, serverId, gameJson).then((result) {
  Fluttertoast.showToast(
    msg: 'setRoleInfo, Msg is: $result',
    gravity: ToastGravity.CENTER);
});

3、登出接口

接口用途：

为了更好的统计该用户/玩家角色在本次登录后的行为，精准标识和打击有恶意行为的用户/玩家。

接入须知：

1. 须在 SDK 初始化接口被调用后方可调用，在用户/玩家退出当前角色（包括切换角色）或者退出游戏时调用接口。
2. 此接口主要用于判断用户/玩家本次生命周期，不强制要求接入。
3. 如果未调用初始化，此接口默认为空，不会执行任何逻辑。

函数原型：

Future<void> logOut()

示例代码：

_htprotectPlugin.logOut();

4、获取凭证

接口用途：

用于关键业务节点风险防控场景中，比如注册、登录、领劵、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口，获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果，并根据结果进行处置。

接口适用场景为:
1、游戏类应用，当 SDK 数据上报接口被屏蔽导致数据上报失败时，通过 getToken 接口获取 SDK 采集信息，并由客户服务端传递给易盾服务器；
2、全类型应用，在关键业务节点主动调用检测时，通过 getToken 接口获取检测凭证，由客户服务端通过 token 凭证从易盾服务器查询检测结果。

接入须知：

1. 须在 SDK 初始化且用户同意隐私政策后才能调用该接口，网易易盾隐私说明。
2. 内部存在网络请求，只允许在子线程上调用。

函数原型：

Future<Map<dynamic, dynamic>> getToken(int timeout, String businessId)

参数说明：

• 入参说明：

参数	说明	必要性
businessId	业务 ID	必填，由易盾后台分配，并在官网“服务管理”中查询
timeout	函数超时时间	必填，单位毫秒，[1000,10000]，此区间外的默认为3000

• 回调参数说明：

回调参数	类型	描述
code	int	结果码，不同结果码含义如下： 200：表示调用成功，其他结果码均表示调用失败； 201：SDK未初始化； 202：在主线程运行； 203：businessId不合法； 204：其他情况
token	String	当 code 为200时，返回正常token。当网络状态不佳或者超时时，会返回离线 token

示例代码：

_htprotectPlugin.getToken(3000,"易盾业务id").then((result) {
  var code = result['code'];
  String token = result['token'];
  Fluttertoast.showToast(
    msg: 'code is $code, token is: $token',
    gravity: ToastGravity.CENTER);

});

5、交互接口（ioctl）

接口用途：

用于在客户端查询 SDK 采集的基础数据、设置需要传递给 SDK 数据（比如初始化配置内容、check 结果信息等）、及其他可能的定制功能服务。

接入须知：

接口调用前置条件是：调用了初始化接口并且同意隐私政策之后。

函数原型：

Future<String> ioctl(int request, String data)

参数说明：

参数	说明	必要性
request	16：设置配置信息，防止初始化失败情况下，客户可以通过服务端请求初始化配置并传递给SDK 17：设置相应信息，客户服务端将check结果传递给SDK，便于执行后续动作 20：获取服务端设备指纹	必填
data	设置信息的附加数据	可选，不需要可填null

回调参数说明

(1) 设置配置信息

向风控 SDK 配置传递从易盾服务器获取到的产品的配置信息（主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取配置信息的情况）。

配置信息：

初始化接口需设置callback

如果callback的code返回400，将msg发送到服务端，再发送到易盾服务端

易盾服务端的返回结果即为配置信息

示例代码：

_htprotectPlugin.ioctl(16,"config").then((result) {
  Fluttertoast.showToast(
    msg: 'result is: $result',
    gravity: ToastGravity.CENTER);

});

返回值： 返回值为一个json：

{"s":0,"v":33554433}//s：状态，int类型，只有为0，v 字段的值才有意义;
                   // v：版本，long类型(8字节)，配置的版本

返回值	说明
s	0:成功 -1:内存配置加载失败
v	配置的版本号

(2) 设置响应信息

向风控 SDK 配置传递从易盾服务端获取到的命中及响应结果信息，以便 SDK 执行相关处置动作（主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取响应结果的情况）。

响应结果信息：

调用获取凭证(getToken)接口，获取token

将token发送到服务端，在服务端调用check接口，获取结果，其中的 sdkRespData 即为 响应结果信息。

示例代码：

_htprotectPlugin.ioctl(17,"response").then((result) {
  Fluttertoast.showToast(
    msg: 'result is: $result',
    gravity: ToastGravity.CENTER);

});

返回值： 返回值为字符串格式：

返回值	说明
0或者-1	输入数据格式有误
1	解析成功

(3) 获取服务端设备指纹

获取服务端设备指纹，需要在风控后台配置相关配置，请联系技术支持。

示例代码：

_htprotectPlugin.ioctl(20,"").then((result) {
  Fluttertoast.showToast(
    msg: 'result is: $result',
    gravity: ToastGravity.CENTER);

});

返回值： 返回值为字符串格式

注意：除以下返回值外，返回为加密后的设备指纹，需要通过上传至服务端进行解密。

返回值	说明
-1	SDK未初始化
2001	无服务端设备指纹缓存
2002	设备指纹服务端获取失败
2003	设备指纹服务端校验失败
2004	设备指纹本地获取失败
2005	设备指纹本地校验失败

6、安全通信协议接口

接口用途：

该接口用于对通信数据进行白盒加密和白盒 HMAC 签名（相当于 数据校验接口 的升级版本），加密和签名的密钥均会被隐藏，攻击者无法获取，从而保障应用/游戏的通信安全。

最新版本接口（V2.1）更新内容如下：

• 自定义二进制格式，增大分析难度；
• 多重加密，防明文传输；
• 数据将进行校验，防止篡改；
• 支持多算法，一旦加密算法被破解，可及时更新为另一种算法；
• 一次一密，每次加密的密钥都不相同；
• 自定义安全随机数发生器，防止系统随机数接口被篡改，始终生成一样的密钥；
• 防重放攻击；
• 防模拟执行(脱离Android/iOS环境运行)。

接口须知：

• 1、如需使用该接口，请联系易盾获取详细说明文档。

（1）加密数据到服务端

函数原型

Future<void> safeCommToServer(int version, int alg, String input, bool isCrucial);

参数说明

• 入参说明：

参数	类型	说明
alg	int	加密算法
input	String	需要加密的原文

• 回调参数说明：

参数	类型	说明
msg	String	当code = 0 时，msg才存在加密成功的数据
code	int	状态码

示例代码：

_htprotectPlugin.safeCommToServer(version,alg,input,isCrucial).then((result) {    
	Fluttertoast.showToast(
    msg: 'result is: $result',
    gravity: ToastGravity.CENTER);
});

（2）解密服务端的数据

函数原型

Future<Map<dynamic, dynamic>> safeCommFromServer(int alg, int timeout, String input)

参数说明

• 入参说明：

参数	类型	说明
alg	int	加密算法 如果 alg 不等于 0x0，则使用 alg 来进行解密，即指定算法解密，否则使用密文里的算法进行解密
timeout	int	超时时间，单位为秒 如果 timeout不为0，则超过timeout的密文会返回nil
input	NSData	需要解密的密文，由服务端返回

• 回调参数说明：

参数	类型	说明
msg	String	当code = 0 时，msg才存在解密成功的数据
code	int	状态码

示例代码：

_htprotectPlugin.safeCommFromServer(alg,timeout,input).then((result) {
  Fluttertoast.showToast(
    msg: 'result is: $result',
    gravity: ToastGravity.CENTER);
});

7、模拟点击AI识别

接口用途：

批量的模拟点击极大的影响到游戏的正常，特别是工作室的参与，不仅影响到游戏的平台，还影响到游戏方的收入。易盾智能反外挂SDK提供相关的行为检测方案，使用模拟点击行为检测接口时，需要在游戏登录后，并且调用设置用户信息接口，设置role_id等信息后调用。

接入须知：

请在作弊情况较严重的玩法和场景下调用registerTouchEvent和unregisterTouchEvent，开启和关闭点击数据的采集，初次接入建议设置一个玩法和场景id，并同步给易盾，如需接入多个玩法和场景需提前与易盾沟通。 开启registerTouchEvent后，在该场景结束后必须调用unregisterTouchEvent关闭检测逻辑。

（1）开启采集数据

函数原型：

Future<void> registerTouchEvent(int gameplayId, int sceneId)

函数说明：

调用该接口后，开始采集点击事件的相关数据。

参数说明：

参数	说明
gameplayId	玩法id
sceneId	场景id

示例代码：

_htprotectPlugin.registerTouchEvent(gameplayId, sceneId);

（2）关闭数据采集

函数原型：

Future<void> unregisterTouchEvent()

函数说明：

取消点击事件数据采集。

示例代码：

_htprotectPlugin.unregisterTouchEvent();