接口说明

本接口是智能风控服务的在线检测接口，需配合智能风控SDK使用，当SDK获取token后，将token传入该接口获取风险识别结果，详情请参考使用教程。该接口为实时检测接口，同步返回检测结果，当前版本为V5。老版本参考 在线检测接口V4。

鉴权说明

易盾智能风控服务使用签名认证方法对接口进行鉴权，所有接口每一次请求都需要包含签名信息（signature 参数），以验证用户身份，防止信息被恶意篡改。目前支持MD5签名算法，详细信息请参见接口鉴权。

接入须知

1. 如果您没有从客户端智能风控SDK获取到token或者获取到的token是null值，依然建议在业务场景节点（SDK埋点位置，如注册场景）调用检测接口。
2. 请根据接口返回的风险等级进行相应业务处置，为了保障处置动作依据完备，如需对用户进行封号，建议结合用户/玩家的业务数据进行二次判断，或者与易盾技术人员进行二次确认，以确保准确无误。
3. 请控制接口调用频率，频率过高，可能会超过频率限制，导致接口调用失败。

请求说明

请求地址

名称	值
HTTP URL	http://ir-open.dun.163.com/v5/risk/check
HTTP Method	POST

请求头

名称	类型	必填	描述
Content-Type	String	是	固定值："Content-Type:application/json"

 

请求参数

请求参数包括：公共参数和私有参数。其中，公共参数请见公共请求参数，接口私有参数如下：

参数名	类型	必填	描述
token	String	是	智能风控SDK上报数据时返回的 token，调用方需通过智能风控SDK的getToken接口获取该数据。详情请查看客户端接入文档。
ip	String	是	用户/玩家的IP，或当前客户端业务事件发生时的公网IP地址（ipv4）
roleId	String	是	用户/玩家的角色 ID，非游戏类型应用，roleId 可以与 account 相同
account	String	是	用户/玩家的账号
nickname	String	否	用户/玩家的昵称
server	String	否	用户/玩家的角色服务器名称
phone	String	否	用户用于登录的手机号码或者关联的手机号码，默认国内手机号。如有海外手机，需包含国家地区代码，格式为“+447410xxx186（+44即为国家码）”。如果需要加密，支持传入hash值，hash算法：md5(phone)
activityId	String	否	活动的唯一标识，用于标记场景下的细分类别，如：注册-自主注册、注册-受邀请注册；再如：登录-app登录、登录-web登录等
target	String	否	活动操作的目标，比如：A给B点赞，则target为B。如果target是手机号或邮箱，请提供hash值，hash算法：md5(target)。如没有，可传空
email	String	否	用户的邮箱
registerTime	Long	否	用户的注册时间，单位：毫秒
registerIp	String	否	用户的注册IP
level	String	否	用户/玩家的等级
gameVersion	String	否	游戏类型应用的版本号
assetVersion	String	否	游戏类型应用的资源版本号
extData	String	否	额外/拓展的信息，应用 / 游戏方可以自己构建json结构，最大长度：2048。不同场景构建信息见分场景extData接入说明

 

请求参数示例

{
    "businessId": "a0bcmo3aa617x1n62tlhtragdd009wy1",
    "secretId": "b0bcmo3aa617x1n62tlhtragdd009wy2",
    "timestamp": ${currentTimeMs},
    "nonce": "c0bcmo3aa617x1n62tlhtragdd009wy3",
    "version": "500",
    "signature": "d0bcmo3aa617x1n62tlhtragdd009wy4",
    "token": "${riskDataToken}",
    "ip":  "1.1.1.1",
    "roleId":  "xxxxxxx",
    "account":  "yyyyyyy",
    "nickname":  "zzzzzzz",
    "server":  "水之道",
    "level":  "150",
    "gameVersion":  "1.0.2",
    "assetVersion":  "0.2.1",
    "extData": "{\"extJson\":\"分场景构造\"}"
}

响应

响应结果

响应数据格式为：JSON。

响应头为：Content-Type:application/json，具体如下：

参数	类型	描述
code	Integer	响应码，正常情况下为200，异常时，见 附录响应码定义
msg	String	响应码说明，正常情况下返回“ok”，异常时，见 附录响应码定义
desc	String	响应信息描述，非必返，常见错误情况下会返回错误说明或错误参考文档
data	JSONObject	返回数据，格式下表说明

检测结果的数据格式：

参数	类型	说明
riskLevel	Integer	风险等级：0 正常，1 低风险，2 中风险，3 高风险，4 可信源。 风险等级只会返回一个，取本次命中的最高风险等级
hitInfos	List	命中风险信息，例如：[{"type":"12401067","name":"环境风险-ROOT-通用","desc":"风险描述"}]。其中：type类型为String，含义为命中的风险标签type；name类型为String，含义为命中的风险标签对应的名称，命中的标签的上下级名称采用‘-’进行拼接；desc类型为String，含义为风险标签的描述信息，可为空。如果同时命中多个类型，则会返回全部命中风险信息。
taskId	String	检测任务 ID，建议记录存储，便于后续数据查询验证。
sdkRespData	String	风控检测结果加密数据，仅在token数据能成功解析时返回该字段，应用/游戏方可转交给风控 sdk 解析处理。
matchedCustomRules	List	命中自定义规则编号列表
deviceId	String	购买设备指纹功能后，check结果中才会包含deviceId。
matchedRules	List	命中规则编号列表
deviceInfo	JSONObject	设备信息

响应结果示例

• 识别结果正常时：

{
    "code": 200,
    "msg": "ok!",
    "data": {
        "riskLevel": 0,
        "hitInfos": null,
        "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
	"sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs"
        //购买设备指纹功能后，check结果中才会包含deviceId
        "deviceId":"389xfu028f2083u230fuc2"
  },
  "ok":true
}

• 识别结果异常时：

{
    "code": 200,
    "msg": "ok!",
    "data": {
        "riskLevel": 1,
        "hitInfos": [
            {
                "type": "...",
                "name": "xx风险-xxx-xxx",
                "desc": "..."
            },
            {
                "type": "...",
                "name": "xx风险-xxx-xxx",
                "desc": "..."
            }
        ],
        "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
        "sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs",
	// 命中自定义规则列表
        "matchedCustomRules": ["R20230228205054395", "R20230228211555767"],
        //购买设备指纹功能后，check结果中才会包含deviceId
        "deviceId":"389xfu028f2083u230fuc2"，
        //命中规则编号列表
        "matchedRules": ["R20230228205054395", "R20230228211555767"],
        //设备信息
        "deviceInfo": "{...}"
  },
  "ok":true
}

注意事项

• 当返回无数据时，可能原因包括数据处理延时、数据不存在；
• 自动封禁有风险，操作请谨慎，建议参考其他因素综合考虑。

响应返回码

响应返回码见：响应返回码

接入示例代码

开发工具集（SDK）接入

为方便 JAVA 开发者调试和接入API，我们提供了配套的开发工具集（SDK），用于简化API接入流程。SDK中各接口调用方式基本相同，接入方式统一，并提供了一些接口调用过程中常见的异常处理方案。以下介绍了SDK的使用流程，以及使用SDK的简单示例。

• 准备工作

准备步骤详见通用步骤

• 使用方法

该接口的使用方法可参考SDK demo