帮助中心

智能风控 uni-app 接入文档

2024.11.14 16:59:44

隐私说明

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

接入说明

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

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

注意：

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

接入步骤

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

导入插件

将插件文件夹粘贴到工程根目录的nativeplugins文件夹中。导入插件之后一定要自定义基座方可生效，自定义基座说明请参考 https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground

SDK接口调用

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

（1）初始化

插件声明

const htp = uni.requireNativePlugin("htpplugin");

初始化接口

htp.init({
	productId: 'XXXXXXX', // 产品id
	serverType: 1 ,			// 
	channel: 'testchannel', // 渠道名称
}, e => {
	// 回调函数
	uni.showToast({
		title: '响应数据：' + JSON.stringify(e),
		icon: 'none'
	});
})

（2）登录接口

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

let json = {GameVersion: 'testGameVersion', AssetVersion: 'testAssetVersion'};
let stringJson = JSON.stringify(json);
htp.setRoleInfo({
	businessId: 'xxxxxxxxxxxxxxxxxxxxx',
	roleId: 'testroleId' ,
	roleName: 'testroleName' ,
	roleAccount: 'testroleAccount' ,
	roleServer: 'testroleServer' ,
	serverId: 1 ,
	gameJson: stringJson ,
}, e => {
	// 回调函数
	uni.showToast({
		title: '响应数据：' + JSON.stringify(e),
		icon: 'none'
	});
})

验证SDK接入是否正确

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

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

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

SDK 接入调用说明

SDK 初始化接口

接口用途：

用于初始化智能风控 SDK。

接入须知：

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

函数原型：

init( String productId,
      int serverType,
      String channel)

参数说明：

入参说明：

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

回调参数说明：

回调参数	类型	描述
code	int	初始化结果code码 200：成功 199：初始化参数错误，如productId不合法或者过期 400：请将 msg 发送到贵方服务端，由贵方服务端通过[getConfig接口配置下发接口](https://support.dun.163.com/documents/761315885761396736?docId=771983453572567040)转发给易盾服务端，由易盾服务端响应
msg	String	初始化结果详情

示例代码：

htp.init({
	productId: 'XXXXXXX', // 产品id
	serverType: 1 ,			// 服务器归属地
	channel: 'testchannel', // 渠道名称
}, e => {
	// 回调函数
	uni.showToast({
		title: '响应数据：' + JSON.stringify(e),
		icon: 'none'
	});
})

设置用户信息接口

接口用途：

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

接口须知：

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

函数原型：

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	游戏类型应用的资源文件版本号

示例代码：

let json = {GameVersion: 'testGameVersion', AssetVersion: 'testAssetVersion'};
let stringJson = JSON.stringify(json);
htp.setRoleInfo({
	businessId: 'xxxxxxxxxxxxxxxxxxxxx',
	roleId: 'testroleId' ,
	roleName: 'testroleName' ,
	roleAccount: 'testroleAccount' ,
	roleServer: 'testroleServer' ,
	serverId: 1 ,
	gameJson: stringJson ,
}, e => {
	// 回调函数
	uni.showToast({
		title: '响应数据：' + JSON.stringify(e),
		icon: 'none'
	});
})

函数返回：

注：iOS没有回调值
回调参数说明：

回调参数类型描述

code int 0:成功
201:未初始化
203:businessId 不合法

回调参数	类型	描述
code	int	0:成功 201:未初始化 203:businessId 不合法

登出接口

接口用途：

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

接入须知：

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

函数原型：

logOut()

示例代码：

Future<void> logOut()

同步获取凭证

接口用途：

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

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

接入须知：

需要在 SDK 初始化且用户同意隐私政策后才能调用该接口，网易易盾隐私说明。
该函数内部会进行网络请求。

函数原型：

getToken(int timeout, String businessId)

参数说明：

入参说明：

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

返回值说明：

返回字符串格式的JSON

返回值	类型	说明
code	int	结果码，不同结果码含义如下：200：表示调用成功，其他结果码均表示调用失败；201：SDK未初始化；202：在主线程运行；203：businessId不合法；204：其他情况
codeStr	string	结果码对应的字符说明，200：success；201：error. not init；202：error. run on main thread；203：businessId invalid；204：gen token error
token	string	当 code 为200时，返回正常token。当网络状态不佳或者超时时，会返回离线 token
businessId	string	由易盾后台分配，并在官网“服务管理”中查询

示例代码：

var result = htp.getToken({timeout: 1000,businessId: 'ab51b8dbadb6894192eeeaafd6973d0e',});

异步获取凭证

接口用途：

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

接入须知：

需要在 SDK 初始化且用户同意隐私政策后才能调用该接口，网易易盾隐私说明。
该函数内部会进行网络请求。

函数原型：

getTokenAsync(int timeout, String businessId)

参数说明：

入参说明：

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

回调参数说明：

回调参数	类型	说明
code	int	结果码，不同结果码含义如下：200：表示调用成功，其他结果码均表示调用失败；201：SDK未初始化；202：在主线程运行；203：businessId不合法；204：其他情况
codeStr	string	结果码对应的字符说明，200：success；201：error. not init；202：error. run on main thread；203：businessId invalid；204：gen token error
token	string	当 code 为200时，返回正常token。当网络状态不佳或者超时时，会返回离线 token
businessId	string	由易盾后台分配，并在官网“服务管理”中查询

示例代码：

htp.getTokenAsync({
	timeout: 1000,
	businessId: 'ab51b8dbadb6894192eeeaafd6973d0e',
}, e => {
	// 回调函数
	uni.showToast({
		title: '响应数据：' + JSON.stringify(e),
		icon: 'none'
	});
})

交互接口（ioctl）

接口用途：

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

接入须知：

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

函数原型：

ioctl(int request, String data)

参数说明：

入参说明：

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

回调参数说明：

回调参数	类型	描述
msg	String	入参 request = 16，返回值为字符串格式的JSON {"s":0,"v":33554433} //s：状态，int类型，只有为0，v 字段的值才有意义; // v：版本，long类型(8字节)，配置的版本入参 request = 17，返回值为字符串格式： 0或者-1，输入数据格式有误；1为解析成功入参 request = 20，返回值为字符串格式：-1，SDK未初始化；2001，无服务端设备指纹缓存；2002，设备指纹服务端获取失败；2003，设备指纹服务端校验失败；2004，设备指纹本地获取失败；2005，设备指纹本地校验失败

上一篇：flutter接入下一篇：鸿蒙端接入(ArkTS)

对文档做个评价吧：

如果遇到产品相关问题，您可提交工单或在线咨询寻求帮助。

在线咨询电话咨询：95163223 免费试用