设备标签接口

最近更新时间:2019-04-01 10:06:13

总体描述

本文说明腾讯广告反欺诈在线查询接口的使用方法和协议规范。通过本查询接口,可以实时查询广告流量的虚假欺诈嫌疑。

接口定义

接口总述

  • 接口采用 Protobuf + UDP 协议,请求和响应数据均为 UTF-8 编码。
  • 接口请求域名:api.telesafe.qq.com
  • 接口名:BlackLibQuery。
  • 查询请求报文内容包含:4字节包体长度(不含长度数据的4字节)+请求消息。
  • 查询响应报文内容包含:4字节包体长度(不含长度数据的4字节)+ 响应消息。

请求报文

  • 请求消息头部 req_header 参数说明:
参数 是否必选 类型 说明
appid String 请求方唯一 ID,16个字符,每次请求时传递,用于身份识别。
timestamp Int 从格林威治时间1970年01月01日00:00:00起至现在的总秒数,精确到秒,与标准时间偏差5分钟之内。
v String 请求接口版本,此处填1.1。
nonce String 单次值,随机字符串,每次请求都必须不同,防止重放攻击。
echostr String 随机字符串,服务器原样带回,客户端校验,长度16个字节。
sign String 请求参数签名,以下两种字符串拼接后,经 MD5 计算出的32个字符的后16个字符:
  • 1. header 按必选字段 key 以字典序排序后,value 拼接(不包括 sign 字段)
  • 2. secret(固定密钥,16位),服务端分配
    • 请求消息体 req_body 参数说明:
      req_body 是对请求内容 json 结构的加密字符串,其中请求内容定义如下:
    参数名 是否必选 类型 说明
    sub_appid int 子业务 ID。
    scene int 业务场景ID,详情请参见下文业务场景 ID 说明
    query_info string 查询信息,详情请参见下文 query_info 参数说明
    • 业务场景 ID 说明:
    场景 ID 场景描述
    5001
  • 查询时机:用户通知广告位时。欺诈者可能使用非正常用户的设备和虚假的广告位,用来骗取利益。
    • query_info 参数说明:
      query_info 是一个 json 结构,定义如下:
    参数 是否必选 类型 说明
    ip String IP。
    os_type Int 操作系统类型:
  • 0:未知。
  • 1:Android。
  • 2:iOS。
  • 3:Windows。
  • os_ver String 操作系统版本号,建议提供。
    imei String Andriod 设备的 IMEI。
    mac String MAC 地址,建议提供。
    phone_num String 电话号码。
    user_agent String 用户端类型。
    app String 用户端应用。
    package String 应用包名。
    device_maker String 设备制造商。
    device_module String 设备型号。
    access_mode String 入网方式,可取值有:wifi、4g、3g、2g。
    sp String 运营商(移动、联通、电信等)。
    device_w String 设备屏幕分辨率宽度像素数。
    device_h String 设备屏幕分辨率高度像素数。
    imp_instl String 是否全屏插广告:
  • 0:否。
  • 1:是。
  • imp_banner_w String 广告位宽度。
    imp_banner_h String 广告位高度。
    url String 网址。
    location String 用户地址。
    lat Float 纬度。
    lng Float 经度。
    context String 上下文信息。
    idfa String iOS 的 idfa。
    idfa_md5_encrypted Int idfa 是否 MD5 加密。
    imei_md5_encrypted Int IMEI 是否 MD5 加密。
    mac_md5_encrypted Int MAC 是否 MD5 加密。
    promote_package_name String 推广 App 的 packagename。
    promote_app_downloaded Int 推广 App 是否下载:
  • 0:否。
  • 1:是。
  • 2:未知。
  • promote_app_installed Int 推广 App 是否安装
  • 0:否。
  • 1:是。
  • 2:未知。
    • 加密过程:
      1. 对请求内容用 AES 加密,加密模式 ECB ,填充方式全0,密钥为分配的 secret。
      2. 对加密后的数据经 Base64 编码后,得到的字符串作为 req_body 的最终值。

    响应报文

    • 响应消息头 rsp_header 参数说明:
    参数 是否必选 说明
    status 返回结果码:
  • 0:请求处理成功。
  • 100:错误的 post 数据格式。
  • 101:错误的请求消息头。
  • 102:错误的请求参数 - appid。
  • 103:错误的请求参数 - timestamp。
  • 104:错误的请求参数 - body。
  • 105:错误的请求参数 - v。
  • 106:错误的请求参数 - nonce。
  • 107:错误的请求参数 - sign。
  • 108:错误的请求类型 - echostr。
  • 109:错误的请求消息体。
  • 110:错误的加解密方式。
  • 201:访问量超过限制。
  • 500:未知处理状态。
  • 501:服务处理错误。
  • msg 结果/原因描述。
    echostr 随机字符串,服务器原样带回,客户端校验,长度16个字节。
    • 响应消息体 rsp_body 参数说明:
      rsp_body 是对响应内容 json 结构加密后的字符串,加密方式参照请求体 req_body 加密过程,解密过程与加密过程逆向即可。解密后的 json 结构如下:
    参数 是否必选 类型 说明
    evil_level String 恶意等级,取值0 - 100,值越大表示恶意等级越高。
    tag String 标签。

    示例代码

    • Request 示例:
      {
        "req_header": {
            "appid": "xxxx",
            "nonce": "59f5c4a40e8634f1",
            "timestamp": 1408103878,
            "v": "1.1",
            "echostr": "1234567890123456",
            "sign": "7eba379599053ee5"
        },
        "req_body": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
      其中 req_body 的原始数据为:
      {
         "scene":5001,
         "query_info":
         {
      "ip":"2.2.2.2",
      "imei":"46874874874",
      "phone_num":"18989898989",
      "user_agent":"ios 10.1.1",
      "app":"微博",
      "package":"weibo-v3.1.20d",
      "device_maker":"apple",
      "device_module":"iphone6s-A1700",
      "mac":"34-64-A9-E6-90-A2",
      "access_mode":"wifi",
      "sp":"电信",
      "device_w":"1980",
      "device_h":"1270",
      "imp_instl":"0",
      "imp_banner_w":"300",
      "imp_banner_h":"800",
      "url":"http://xxxx.com/xxx/",
      "location":"广东省深圳市南山区深南大道",
      "lat":132.908002,
      "lng":23.00983,
      "context":"其他扩展信息…"
          }
      }
    • Response 示例:
      {
        "rsp_header": {
            "status": "0",
            "msg": "请求成功",
            "echostr": "1234567890123456"
        },
        "rsp_body": "xxxxxxxxxxxx"
      }

    其中 rsp_body 解密后如下:

     {
    "evil_level":77
     }
     // json obj,返回对应的结果

    接口使用

    1. 申请接口使用权限。
    2. 调用对应的接口即可查询。