智能风控 uni-app 接入文档
隐私说明
请参照网易易盾隐私政策,请将易盾隐私政策链接放到应用“用户协议”中。
接入说明
接入“智能风控” SDK,开发者需要完成以下步骤:
1. 根据应用/游戏开发平台,将SDK拷贝到指定的工程目录,并修改项目配置;
2. 接入风控SDK必接接口,根据业务需求接入建议接口;
3. 测试风控SDK接入是否正确;
4. 验证风控SDK功能效果;
5. 按业务常规发版流程进行测试与发版
注意:
接入步骤
导入插件
将插件文件夹粘贴到工程根目录的nativeplugins文件夹中。导入插件之后一定要自定义基座方可生效,自定义基座说明请参考 https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground
SDK接口调用
部分产品相关参数请用账号登录易盾官网控制台获取参考
(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 不合法
登出接口
接口用途:
为了更好地统计该用户/玩家角色在本次登录后的行为,精准标识和打击有恶意行为的用户/玩家。
接入须知:
- 须在 SDK 初始化接口被调用后方可调用,在用户/玩家退出当前角色(包括切换角色)或者退出游戏时调用接口。
- 此接口主要用于判断用户/玩家本次生命周期,不强制要求接入。
- 如果未调用初始化,此接口默认为空,不会执行任何逻辑。
函数原型:
logOut()
示例代码:
Future<void> logOut()
同步获取凭证
接口用途:
用于关键业务节点风险防控场景中,比如注册、登录、领劵、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口,获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果,并根据结果进行处置。
接口适用场景为:
1、游戏类应用,当 SDK 数据上报接口被屏蔽导致数据上报失败时,通过 getToken 接口获取 SDK 采集信息,并由客户服务端传递给易盾服务器;
2、全类型应用,在关键业务节点主动调用检测时,通过 getToken 接口获取检测凭证,由客户服务端通过 token 凭证从易盾服务器查询检测结果。
接入须知:
函数原型:
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',});
异步获取凭证
接口用途:
用于关键业务节点风险防控场景中,比如注册、登录、领劵、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口,获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果,并根据结果进行处置。
接口适用场景为:
1、游戏类应用,当 SDK 数据上报接口被屏蔽导致数据上报失败时,通过 getToken 接口获取 SDK 采集信息,并由客户服务端传递给易盾服务器;
2、全类型应用,在关键业务节点主动调用检测时,通过 getToken 接口获取检测凭证,由客户服务端通过 token 凭证从易盾服务器查询检测结果。
接入须知:
函数原型:
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,设备指纹本地校验失败