在线检测接口V6

2023.11.29 14:35:59

    接口说明

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

    鉴权说明

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

    接入须知

    1. 如果您没有从客户端智能风控SDK获取到token或者获取到的token是null值,依然建议在业务场景节点(SDK埋点位置,如注册场景)调用检测接口。
    2. 请根据接口返回的风险等级进行相应业务处置,为了保障处置动作依据完备,如需对用户进行封号,建议结合用户/玩家的业务数据进行二次判断,或者与易盾技术人员进行二次确认,以确保准确无误。
    3. 请控制接口调用频率,默认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))。
    email 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信息

    hitInfos命中风险信息

    字段名称 类型 支持的接口版本 说明
    type Integer 600及以上版本 风险标签type。如果同时命中多个类型,则会返回全部命中风险信息
    name String 600及以上版本 命中的风险标签对应的名称,命中的标签的上下级名称采用‘-’进行拼接
    riskLevel Integer 602及以上版本 风险等级。如果同个风险标签类型被命中多次,则会返回风险等级最高的

    Androd设备信息

    字段名称 类型 说明
    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 当前电量信息

    IOS设备信息

    字段名称 类型 说明
    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,分值越高被黑产持有的概率越高

    IP信息

    字段名称 类型 支持的接口版本 说明
    basicInfo JSONObject 603及以上版本 IP基础信息,在check接口返回配置中设置,字段详见IP基础信息
    ipRiskInfo JSONObject 603及以上版本 IP画像信息,开通了IP画像功能的才会返回,字段详见IP画像信息

    IP基础信息

    字段名称 类型 支持的接口版本 说明
    isp String 603及以上版本 运营商
    continent String 603及以上版本 大洲
    country String 603及以上版本 国家
    province String 603及以上版本 省份
    city String 603及以上版本 城市
    longitude String 603及以上版本 经度
    latitude String 603及以上版本 纬度

    IP画像信息

    字段名称 类型 支持的接口版本 说明
    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

    Online Chat Tel:95163223 Free trial