在线检测接口V6
2023.11.29 14:35:59
接口说明
本接口是智能风控服务的在线检测接口,需配合智能风控SDK使用,当SDK获取token后,将token传入该接口获取风险识别结果,详情请参考使用教程。该接口为实时检测接口,同步返回检测结果,当前版本为V6。老版本参考 在线检测接口V5和在线检测接口V4。
鉴权说明
易盾智能风控服务使用签名认证方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature 参数),以验证用户身份,防止信息被恶意篡改。目前支持MD5签名算法,详细信息请参见接口鉴权。
接入须知
- 如果您没有从客户端智能风控SDK获取到token或者获取到的token是null值,依然建议在业务场景节点(SDK埋点位置,如注册场景)调用检测接口。
- 请根据接口返回的风险等级进行相应业务处置,为了保障处置动作依据完备,如需对用户进行封号,建议结合用户/玩家的业务数据进行二次判断,或者与易盾技术人员进行二次确认,以确保准确无误。
- 请控制接口调用频率,默认qps为1000,频率过高,可能会超过频率限制,导致接口调用失败。上线前有需要提升qps需要可以联系商务同学。
请求说明
请求地址
名称 | 值 |
---|---|
HTTP URL | http://ir-open.dun.163.com/v6/risk/check |
HTTP Method | POST |
请求头
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 固定值:"Content-Type:application/json" |
请求参数
请求参数包括:公共参数和私有参数。其中,公共参数请见公共请求参数,接口私有参数如下:
参数名 | 类型 | 必填 | 最大长度 | 支持的接口版本 | 描述 |
---|---|---|---|---|---|
token | String | 是 | - | 600及以上版本 | 在客户端调用getToken服务后返回给客户端的检测凭证:token。 - 正常情况下token长度为 40 byte - 网络不通或者域名被屏蔽情况下,生成离线token,平均长度在8kb左右,请勿对token进行截断 详情请查看客户端接入说明文档。 |
account | String | 是 | 256 | 600及以上版本 | 用户账号标识,建议使用业务方用户的UID,标记用户的唯一身份。 |
roleId | String | 是 | 256 | 600及以上版本 | 用户角色ID,适用于支持同一个账号下创建不同角色的业务(如游戏不同区服的角色)。 如无roleId,可传入固定值“1”,或与account相同的值。 |
nickname | String | 否 | 256 | 600及以上版本 | 用户账号/角色的昵称。 |
server | String | 否 | 32 | 600版本支持,601版本已经移除,不再支持 | 用户/玩家的角色服务器名称 601版本后,server已移入反外挂场景中,请通过反外挂场景参数(sceneData)的serverId字段描述按需填写 |
ip | String | 是 | 64 | 600及以上版本 | 用户的IP,或当前客户端业务事件发生时的客户端请求IP地址(ipv4格式)。 |
phone | String | 否 | 64 | 600及以上版本 | 用户账号关联的手机号码(部分业务,账号名=手机号码),默认为国内手机号码。 如有海外手机号码,需要包含国家地区代码,格式为“+447410xxx186”(+44即为国家码)。 支持数据加密,请传入hash值(hash算法:md5(phone))。 |
String | 否 | - | 600及以上版本 | 用户账号关联的电子邮箱地址,如需要进行加密,请使用hash值(hash算法:md5(email))。 注意:必须是有效的电子邮件格式,如:xx@xx.com。 |
|
target | String | 否 | 256 | 600版本支持,601版本已经移除,不再支持 | 活动操作的目标,比如:A给B点赞,则target为B。如果target是手机号或邮箱,请提供hash值,hash算法:md5(target)。如没有,可传空 601版本后,target已移入不同的场景字段中,请通过场景参数(sceneData)字段描述按需填写 |
registerTime | Long | 否 | 13 | 600及以上版本 | 用户/角色注册、创建时间点。请传入时间戳,单位:毫秒。 注意:如传入,系统会进行参数格式强校验,参数长度必须是13位,如:1689733747268。 |
registerIp | String | 否 | 64 | 600及以上版本 | 用户/角色注册、创建时的IP地址,如有记录,可传入辅助进行风险判断。 |
level | String | 否 | 32 | 600及以上版本 | 用户账号等级、财富等级等,有助于对不同等级用户设置分层策略,方便业务进行精细化安全运营。 注意:level 由业务自定义,风控系统除长度外不会有任何其他校验手段,请业务需要自行管理、维护 level 字典。 |
identity | String | 否 | - | 601及以上版本 | 当前用户身份,有助于对不同身份用户设置分层策略,方便业务进行精细化安全运营。 注意:仅接收以下内容,如传入,系统将会强制校验传入值合法性。 - vistor:游客 - commonUser:普通用户 - seniorUser:高级用户(如vip、主播) - other:其他身份 |
payUser | Boolean | 否 | - | 601及以上版本 | 当前用户是否付费用户,有助于对用户设置分层策略。 注意:仅接收布尔值,如传入,系统将会强制校验传入值合法性。 - true:付费用户 - false:非付费用户 |
verified | Boolean | 否 | - | 601及以上版本 | 当前用户是否认证用户(实名/真人认证),有助于对不同安全等级用户设置分层策略。 注意:仅接收布尔值,如传入,系统将会强制校验传入值合法性。 - true:认证用户 - false:非认证用户 |
gameVersion | String | 否 | 32 | 600版本支持,601版本已经移除,不再支持 | 游戏类型应用的版本号 601版本后,gameVersion已移入反外挂场景中,请通过反外挂场景参数(sceneData)的gameVersion字段描述按需填写 |
assetVersion | String | 否 | 32 | 600版本支持,601版本已经移除,不再支持 | 游戏类型应用的资源版本号 601版本后,assetVersion已移入反外挂场景中,请通过反外挂场景参数(sceneData)的assetVersion字段描述按需填写 |
activityId | String | 否 | 256 | 600及以上版本 | 事件的细分标记,用于标记场景事件下的细分类别,如同样是促销活动,可用于区分:双十一促销、618促销;再如同样是邀请拼团活动,activityId标记本次邀请的唯一识别ID |
deviceId | String | 否 | 128 | 600及以上版本 | 当前用户的设备ID。 注意:如果通过SDK模式接入,则可不传,优先使用SDK生成的设备ID,API模式下强烈建议传入。 |
sceneData | String | 是 | - | 600及以上版本 | 不同业务场景下,需要传入的场景数据存在差异,具体请看下述场景参数描述。不同场景接入说明 注意:如接入场景为“其他”(即不指定某个具体的场景,或规范中的标准场景),则sceneData可传空。 |
extData | String | 否 | 2048 | 600及以上版本 | 根据业务定制需求,额外需要传入系统的信息,可用于配置业务定制的检测规则。 |
请求参数示例
{
"businessId": "a0bcmo3aa617x1n62tlhtragdd009wy1",
"secretId": "b0bcmo3aa617x1n62tlhtragdd009wy2",
"timestamp": ${currentTimeMs},
"nonce": "c0bcmo3aa617x1n62tlhtragdd009wy3",
"version": "601",
"signature": "d0bcmo3aa617x1n62tlhtragdd009wy4",
"token": "${riskDataToken}",
"ip": "1.1.1.1",
"roleId": "xxxxxxx",
"account": "yyyyyyy",
"nickname": "zzzzzzz",
"level": "150",
"identity": "vistor",
"payUser": true,
"verified": false,
"deviceId": "381xfu028f2083u230fuc2",
"sceneData": "{\"loginType\":\"userPassword\",\"appChannel\":\"app_store\",\"registerDay\":999,\"hashPassword\":\"adfdafjk123kjfkljdaf\",\"identity\":\"visitor\",\"paidUser\":false,\"verifiedUser\":false}"
"extData": "{\"otherInfo\":\"其他字段信息\"}"
}
响应
响应结果
响应数据格式为:JSON。
响应头为:Content-Type:application/json,具体如下:
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应码,正常情况下为200,异常时,见 附录响应码定义 |
msg | String | 响应码说明,正常情况下返回“ok”,异常时,见 附录响应码定义 |
desc | String | 响应信息描述,非必返,常见错误情况下会返回错误说明或错误参考文档 |
data | JSONObject | 返回数据,格式下表说明 |
参数 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
riskLevel | Integer | 600及以上版本 | 风险等级:0 正常,1 低风险,2 中风险,3 高风险,4 可信源。 风险等级只会返回一个,取本次命中的最高风险等级 |
hitInfos | List | 600及以上版本 | 命中风险信息,例如:[{"type":"12401067","name":"环境风险-ROOT-通用","riskLevel":"风险等级"}]。其中:type类型为String,含义为命中的风险标签type;name类型为String,含义为命中的风险标签对应的名称,命中的标签的上下级名称采用‘-’进行拼接;riskLevel类型为Integer,含义为风险等级。如果同时命中多个类型,则会返回全部命中风险信息。详细风险标签参考智能风控风险标签 |
taskId | String | 600及以上版本 | 检测任务 ID,建议记录存储,便于后续数据查询验证。 |
sdkRespData | String | 600及以上版本 | 风控检测结果加密数据,仅在token数据能成功解析时返回该字段,应用/游戏方可转交给风控 sdk 解析处理。 |
deviceId | String | 600及以上版本 | 购买设备指纹功能后,check结果中才会包含deviceId。 |
pcId | String | 603及以上版本 | 如当前为在PC机器上的多开Android模拟器环境,则返回PC的指纹ID,开通了设备指纹功能的才会返回。 |
matchedRules | List | 600及以上版本 | 命中规则编号列表 |
matchedCustomRules | List | 600及以上版本 | 命中自定义规则编号列表 |
deviceInfo | JSONObject | 600及以上版本 | 设备信息, Android设备返回的字段见Androd设备信息,IOS设备返回字段见IOS设备信息 |
evidences | List | 600及以上版本 | 证据信息 |
phoneInfo | JSONObject | 603及以上版本 | 手机号画像信息,开通了手机号画像功能的才会返回,返回的字段见手机号画像信息 |
ipInfo | JSONObject | 603及以上版本 | IP信息,返回的字段见IP信息 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
type | Integer | 600及以上版本 | 风险标签type。如果同时命中多个类型,则会返回全部命中风险信息 |
name | String | 600及以上版本 | 命中的风险标签对应的名称,命中的标签的上下级名称采用‘-’进行拼接 |
riskLevel | Integer | 602及以上版本 | 风险等级。如果同个风险标签类型被命中多次,则会返回风险等级最高的 |
字段名称 | 类型 | 说明 |
---|---|---|
screenInfo | String | 屏幕信息 |
appVersion | String | app版本号 |
bootCount | String | 设备启动次数 |
chargeState | String | 充电状态 |
macRandom | String | 是否开启mac随机化,0:未随机化,1:随机化,2:未知,3:mac地址存在错误 |
screenBright | String | 屏幕亮度 |
checkAdb | String | adb是否开启,0:否,1:是 |
upTime | String | 手机已启动时间 |
osVersion | String | Android版本,如7.0,8.1.0 |
carrierName | String | 运营商 |
lockTime | String | 手机总锁屏时间 |
isFakeCam | String | 是否是虚拟摄像头,0:不是,1:是 |
phoneBrand | String | 手机品牌 |
firstSetupTime | String | 第一次安装时间 |
hasSim | String | 是否存在sim卡,0:无,1:有 |
model | String | 型号 |
isShareScreen | String | 投屏状态判断,0:不是,1:是 |
networkType | String | 网络连接类型,1:wifi,2:2g,3:3g,4:4g,5:5g |
batteryLevel | String | 当前电量信息 |
字段名称 | 类型 | 说明 |
---|---|---|
bootTime | String | 开机时间 |
totalDiskSpace | String | 硬盘大小,单位字节 |
auxo | String | 非完美越狱失效状态,0:未越狱,1:越狱,2:越狱失效 |
macSerialnumber | String | mac序列号 |
chargeStatus | String | 0:未开启电池权限,1:未充电,2:充电中,电池电量小于100,3:充电中,电池电量充满 |
deviceId | String | 客户端本地生产的设备 ID |
isCydiaSubstrate | String | 是否安装CydiaSubstrate,0:否,1:是 |
isAntiJailbreak | String | 是否有反越狱插件,0:否,1:是 |
totalMemory | String | 总内存,单位字节 |
osVersion | String | 手机操作系统版本 |
carrierName | String | 运营商名称 |
model | String | 手机型号 |
cpuUseRate | String | cpu 使用率 |
networkType | String | 网络连接类型,1:wifi,2:2g,3:3g,4:4g,5:5g |
batteryLevel | String | 当前电量信息 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
basicInfo | JSONObject | 603及以上版本 | 手机号基础信息,字段详见手机号基础信息 |
phoneRiskInfo | JSONObject | 603及以上版本 | 手机号画像信息,字段详见手机号风险信息 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
carrier | String | 603及以上版本 | 运营商 |
province | String | 603及以上版本 | 省份 |
city | String | 603及以上版本 | 城市 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
riskType | String | 603及以上版本 | 风险类型 |
riskLevel | Integer | 603及以上版本 | 风险等级:0-低风险,1-中风险,2-高风险 |
riskScore | Double | 603及以上版本 | 风险分值:0.0~1.0,分值越高被黑产持有的概率越高 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
basicInfo | JSONObject | 603及以上版本 | IP基础信息,在check接口返回配置中设置,字段详见IP基础信息 |
ipRiskInfo | JSONObject | 603及以上版本 | IP画像信息,开通了IP画像功能的才会返回,字段详见IP画像信息 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
isp | String | 603及以上版本 | 运营商 |
continent | String | 603及以上版本 | 大洲 |
country | String | 603及以上版本 | 国家 |
province | String | 603及以上版本 | 省份 |
city | String | 603及以上版本 | 城市 |
longitude | String | 603及以上版本 | 经度 |
latitude | String | 603及以上版本 | 纬度 |
字段名称 | 类型 | 支持的接口版本 | 说明 |
---|---|---|---|
riskType | String | 603及以上版本 | 风险类型 |
riskLevel | Integer | 603及以上版本 | 风险等级:0-低风险,1-中风险,2-高风险 |
riskScore | Double | 603及以上版本 | 风险分值:0.0~1.0,分值越高被黑产持有的概率越高 |
响应结果示例
- 识别结果正常时:
{
"code": 200,
"msg": "ok!",
"data": {
"riskLevel": 0,
"hitInfos": null,
"taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
"sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs"
//购买设备指纹功能后,check结果中才会包含deviceId
"deviceId":"389xfu028f2083u230fuc2",
"pcId":"如当前为在PC机器上的多开Android模拟器环境,则返回PC的指纹ID,开通了设备指纹功能的才会返回",
"phoneInfo":{ // 手机号画像信息,开通了手机号画像功能的才会返回
"basicInfo":{
"carrier":"运营商",
"province":"省份",
"city":"城市"
},
"phoneRiskInfo":{
"riskType":"风险类型",
"riskLevel":0,
"riskScore":0.1,
}
},
"ipInfo":{ // IP信息
"basicInfo":{ // IP基础信息,在check接口返回配置中设置
"isp":"运营商",
"continent":"大洲",
"country":"国家",
"province":"省份",
"city":"城市",
"longitude":"经度",
"latitude":"纬度"
},
"ipRiskInfo":{ // IP画像信息,开通了 IP 画像功能的才会返回
"riskType":"风险类型",
"riskLevel":0,
"riskScore":0.1,
}
},
"ok":true
}
- 识别结果异常时:
{
"code": 200,
"msg": "ok!",
"data": {
"riskLevel": 2,
"hitInfos": [
{
"type": "...",
"name": "xx风险-xxx-xxx",
"riskLevel": 1
},
{
"type": "...",
"name": "xx风险-xxx-yyy",
"riskLevel": 2
}
],
"taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
"sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs",
//购买设备指纹功能后,check结果中才会包含deviceId
"deviceId":"389xfu028f2083u230fuc2",
//命中规则编号列表
"matchedRules": ["R20230228205054395", "R20230228211555767"],
// 命中自定义规则列表
"matchedCustomRules": ["R20230228205054395", "R20230228211555767"],
//设备信息
"deviceInfo": "{...}",
// 证据信息
"evidences": ["证据", "证据"]
},
"ok":true
}
注意事项
- 当返回无数据时,可能原因包括数据处理延时、数据不存在;
- 自动封禁有风险,操作请谨慎,建议参考其他因素综合考虑。
响应返回码
响应返回码见:响应返回码
接入示例代码
开发工具集(SDK)接入
为方便 JAVA 开发者调试和接入API,我们提供了配套的开发工具集(SDK),用于简化API接入流程。SDK中各接口调用方式基本相同,接入方式统一,并提供了一些接口调用过程中常见的异常处理方案。以下介绍了SDK的使用流程,以及使用SDK的简单示例。
- 准备工作
准备步骤详见通用步骤
- 使用方法
该接口的使用方法可参考SDK demo