在线检测接口V5

2023.12.18 13:00:21

    接口说明

    本接口是智能风控服务的在线检测接口,需配合智能风控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

    Online Chat Tel:95163223 Free trial