HaiYaSSP_APi对接文档

修订历史
版本 修改时间 修改内容
1.0 2021.05.13 Admin
使用条款
未经书面许可,任何人或任何机构不得向第三方披露、泄露有关本文件的任何内容或细节。本公司拥有修改、调整、增补本文件的权利。

接入说明

  • 媒体方需要向运营人员申请联调地址和正式地址;
  • 基础通信协议采用 HTTP 协议,使用 POST 方法,数据格式为 JSON,编码为 UTF-8;
  • 请求头部Content-Type为application/json;
  • 用 API Server to Server 的方式接入原生广告;

BidRequsetModel
参数名 类型 说明 是否必填(Y/N)
sign string 加密 签名,规则 :md5大写(time+slot_id+token) , 媒体token,slot_id 请联系商务/渠道人员获取 Y
app App 对象 App 相关信息 Y
device Device 对象 设备信息 Y
AppModel
参数名 类型 说明 是否必填(Y/N)
app_ver string App 版本号 Y
slot_id string 广告位ID Y
app_id string 平台申请的appid Y
time long 13位时间戳,精确到毫秒 Y
width int 广告位宽度 Y
height int 广告位高度 Y
Device Model
参数名 类型 说明 是否必填(Y/N)
keyword string 广告关键词,最多长度50 N
ip string 设备 IP,必须是客户端真实获取 IP Y
ipv6 string ipv6 设备公网ipv6,必须是客户端真实获取 IP Y
nw_type int 网络类型,0:未知,1:wifi,2:2G,3:3G,4:4G Y
otor_type int 网络运营商 ,46000:中国移动、46001:中国联通、46003:中国电信 Y
wifi_ssid string wifi名称 N
wifi_bssid string wifi对应的网卡mac地址 N
ua string 浏览器 ua ,必须是客户端系统的 UA Y
device_type int 设备类型,(0 未知、1 phone、 2 pad、 3pc、4 wap) Y
os_type int 客户端操作系,1:Android、 2 :IOS、 Y
os_ver string 系统版本 Y
imsi string 移动设备身份码 N
imei string 安卓 imei Y
imeimd5 string 安卓 imei MD5值 N
android_id string 安卓 ID Y
mac string 设备的 MAC 地址 Y
idfa string IOS 的 idfa ,IOS必填 Y
idfv string IOS 的 idfv,IOS必填 Y
caid string IOS14后idfa的替代方案,广协caid Y
udid string ios 中的 openudid Y
brand string 设备品牌 Y
model string 设备型号 Y
density double 屏幕密度 N
screen_width int 屏幕宽度 Y
screen_height int 屏幕高度 Y
screen_orientation int 横竖屏 0:未知、1:竖屏、2:横屏 N
ln double 经度 N
lt double 纬度 N
oaid string 安卓10 ID,获取不到imei时必填 Y
packages array of string 设备已安装app包名集合 N
serialno string 移动设备序列号 Y
mac_md5 string mac地址的MD5值 Y
boot_mark string 系统启动标识值 Y
update_mark string 系统更新标识 Y
hms_ver string 华为安卓设备的HMS Core 的版本号(华为必传) N
appstore_version string 应用商店版本号(huawei、oppo、vivo 必传) N
请求示例
 {
    "app": {
        "app_ver": null,
        "slot_id": null,
        "time": 0,
        "width": 0,
        "height": 0
    },
    "device": {
        "keyword": null,
        "ip": null,
        "nw_type": 0,
        "otor_type": 0,
        "wifi_ssid": null,
        "wifi_bssid": null,
        "ua": null,
        "device_type": 0,
        "os_type": 0,
        "os_ver": null,
        "imei": null,
        "imeimd5": null,
        "android_id": null,
        "mac": null,
        "idfv": null,
        "idfa": null,
        "udid": null,
        "brand": null,
        "model": null,
        "density": 0.0,
        "screen_width": 0,
        "screen_height": 0,
        "screen_orientation": 0,
        "ln": 0.0,
        "lt": 0.0,
        "packages": null,
        "imsi": null,
        "serialno": null,
        "oaid": null
    },
    "sign": null
}

BidRepostModel
参数名 类型 说明 是否必填(Y/N)
is_success bool 响应状态码 true:成功 Y
msg string 错误消息 Y
ad array of ad 广告集合信息 Y
AdModel
参数名 类型 说明 是否必填(Y/N)
html string html 信息 N
imgsrc string banner类图片路径 N
width int banner类图片宽度 N
height int banner类图片高度 N
title string 广告标题 N
desc string 广告描述 N
img_list array of string 信息流图片地址 N
icon string 图片 icon N
action int 点击行为 1:页面跳转,2 :下载,3:广点通下载 Y
link string 链接地址,如果有宏替换的标识,需要宏替换 Y
deeplink string deeplink 地址,如果有宏替换的标识,需要宏替换 N
app RepostAPP 对象 app的基础信息 N
tracking ExtendTracking 对象 上报地址 N
video Videos 对象 视频相关 N
RepostAppModel
参数名 类型 说明 是否必填(Y/N)
app_name string app名称 [click_action=2]只在下载类广告时生效 N
package_name string app包名 [click_action=2]只在下载类广告时生效 N
app_icon string app图标 [click_action=2]只在下载类广告时生效 N
app_size int app大小 [click_action=2]只在下载类广告时生效 N
ExtendTrackingModel
参数名 类型 说明 是否必填(Y/N)
exposure_tracking array of string 展示上报地址,如果有宏替换的标识,需要宏替换 N
click_tracking array of string 点击上报地址,如果有宏替换的标识,需要宏替换 N
deeplink_evoke array of string deeplink 唤起成功上报地址,如果有宏替换的标识,需要宏替换 N
download_start array of string 下载开始上报地址 ,如果有宏替换的标识,需要宏替换 N
download_complete array of string 下载完成上报地址,如果有宏替换的标识,需要宏替换 N
installation_start array of string 安装开始上报地址 ,如果有宏替换的标识,需要宏替换 N
installation_complete array of string 安装完成上报地址,如果有宏替换的标识,需要宏替换 N
activation array of string 激活上报地址,如果有宏替换的标识,需要宏替换 N
VideosModel
参数名 类型 说明 是否必填(Y/N)
video_url string 广告视频地址 N
video_duration int 视频广告的时长,单位秒 N
prefetch bool 是否预先加载视频 N
video_loaded_trackers array of string 视频加载成功上报地址,如果有宏替换的标识,需要宏替换 N
start_play_trackers array of string 视频播放开始上报地址,如果有宏替换的标识,需要宏替换 N
end_play_trackers array of string 视频播放完成上报地址,如果有宏替换的标识,需要宏替换 N
video_close array of string 关闭视频上报地址,如果有宏替换的标识,需要宏替换 N
video_skip array of string 跳过视频上报地址,如果有宏替换的标识,需要宏替换 N
html string HTML 片段,落地页 H5 模板代码,不为空时使用。必须在视频播放完毕后再渲染 HTML 片段,否则会影响收益 N
html_exposure_tracking array of string HTML 展示上报链接,如果有宏替换的标识,需要宏替换 N
html_clos_tracking array of string HTML 关闭上报链接,如果有宏替换的标识,需要宏替换 N
callback_trackers array of string 服务器激励回调上报 URL N
error array of string 视频播放错误上报地址,如果有宏替换的标识,需要宏替换 N
playpercentages array of Playpercentage对象 播放进度上报地址 N
play_trackers Playtrackers对象 视频扩展上报地址 N
PlaypercentageModel
参数名 类型 说明 是否必填(Y/N)
checkpoint int 时间(秒) N
urls array of string 跟踪上报地址,如果有宏替换的标识,需要宏替换 N
PlaytrackersModel
参数名 类型 说明 是否必填(Y/N)
mute array of string 静音事件上报地址,如果有宏替换的标识,需要宏替换 N
unmute array of string 关闭静音事件上报地址,如果有宏替换的标识,需要宏替换 N
play array of string 播放事件上报地址,如果有宏替换的标识,需要宏替换 N
pause array of string 暂停事件上报地址,如果有宏替换的标识,需要宏替换 N
replay array of string 重新播放事件上报地址,如果有宏替换的标识,需要宏替换 N
fullscreen array of string 全屏事件上报地址,如果有宏替换的标识,需要宏替换 N
unfullscreen array of string 退出全屏事件上报地址,如果有宏替换的标识,需要宏替换 N
upscroll array of string 上滑事件上报地址,如果有宏替换的标识,需要宏替换 N
downscroll array of string 下滑事件上报地址,如果有宏替换的标识,需要宏替换 N
响应Json示例
    "is_success": true,
    "msg": "",
    "ad": [
        {
            "html": "",
            "imgsrc": "",
            "width": 640,
            "height": 150,
            "title": "现金红包免费领【100元】",
            "desc": "这是一条信息流测试广告位",
            "img_list": [
                "https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fhbimg.b0.upaiyun.com%2F84d7bcec4e7c82a95ac92f0d0cd296c805eae9182911a-23PYDo_fw658&refer=http%3A%2F%2Fhbimg.b0.upaiyun.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1633837523&t=eb09e1611f17c6fa0bf587562ab46ab6"
            ],
            "icon": null,
            "action": 1,
            "link": "http://cfg.aiclk.com/hdjump?iclicashid=7755216",
            "deeplink": "",
            "app": {
                "app_name": "",
                "package_name": "",
                "app_icon": "",
                "app_size": 0
            },
            "tracking": {
                "exposure_tracking": [
                    "/api/e?s=H4sIAAAAAAAACg3RRaKrMAAAwAN1EVyWuEOLlZddoYXgHuT0_88VhlJWg-6wWLS9QEMu0RhJaaf6Dr7h2hULBcnZxvCGYMtOIfY8m7TE8dKprBJZ8hT39pPkmhDfVf0X58ziW5gbbkzUhoQdYXWmmmlJmDWZD4LatXvnittr-KZlFhV-A1J61YWcnp_nvPRJKAN3V39uvFx-mW_n6I8y8dSDQxyWxCfRy0s_kRCgN0O9cUkba_RSf5IrqR7JTA7KkDkwKzjulybTbOd52eMwabkCP2uMYOEiUpG-fhztVQyH8kYIQZ3f9XcYaEBkw1Ku2jrIdcKemAHCwF623eh6nQdBAbA_vk3y7CY_ov1eWRGqC5Dc6JnyJ_0hWjo5nmH8a9SupebBjzJm5TGLP9umyWKA84bHzjMQtqUMpyHu0_MVbdd-lptX8Prel3_g2D7hXF187ZAG8LiChJZD807jsOzxUfq8tatIFKsH9T-Ik_PmQxdYDT13th9Yo_Kk1hcvPG3eGRylNR-SrhIFXQ_UfGtQsaBnHGg0E3X7K2AarYisZPRQsl_huv791YA7Meqx_gx3safXHgpwfpb5oZseZhSpZo1Zy_fjOTO3aIs1Naz5HFRR7VO7gVaLYcXsTo6cfynj_u4H5ULA5xho6wObEJaJidstJi2uTZmQi60cPTLoLAITDlpy4mVSsV6EwgNLHLccTUqBi0Vp0MI1SO6Dsi4XyYB2Wp9-MsgVy-l7j_xWcu_mYSae--sHrokH12vSjn9xNh5_2kJWoYXA4mxZiN5y8z7SJGQ7FfKm5WFsR4d0-qdNg3_PSpbeAAMAAA"
                ],
                "click_tracking": [
                    "/api/c?s=H4sIAAAAAAAACgXB16JDMAAA0A_qQxA1HinKtarUyBttxN6jzdffc84yn66ozAfkvKtAZ-zDck1UU__zXLv3wiF2_jsQRWBLv1Lkun-sJY8_g0uJfGW_8t7mr0KXIkrqLCr4xbMOYaAHU9-Vw5ZWe6r5lkVpk3rAr52_3v5F7W_4xGUavr0GxHA1pALOj--89K-nCpxdw060_Lyy2L6jN6rMw_BPeVheHlsFbpyHkl8lPJccJbyvYaBhxVE0l-Unu0orc-BXcNJAV-G1c930cppQJQBbY4jeTsXelI8XhTuJ0FDSqqqQISog6FxiUgnM5jvWh-lrj4Hnu-0CgKxVQ3oL4SADjk2YPWPPOPkKha0dBYZGtaswaHDDW7stJtcsHjWIz-TXxUiQP1nu9xwcCdft-1peFCAEQ3LIt4PBjiAV0wuVFHV7XLbQMp9ixCa6Zgr5oxyZH7Mv167q1WIbgU8xnkQsuW-ehrdQulBfFBrR99zXOCSEA55Ep1xJVE4Tu-SJW8O2b44Qtj_4ZA0mHr4Ch6VWIrcYZxYu6dfJ1_2SDQ0-a7WNNrPMhVZ9UJeFhrA9_eoyGuqo6JeGRJ1h3yUdR3vipnsyG1PkeNPPE5_E7691KmSdFS3GycwBBVp_VEjtP4_sEu6oCWF56_ajJWroOFeO9WeJbbgNugUnvPph3tFDTBkw4FcTTDMqALnzzmJ16MpyjCsyqi4v4I0BhbVs31hSV-y9ZiYm-YhDl10Ex9GpWtpn2S8bHE9JzOGW2wxPiRC4XAIz9EzrUSh-3aboRCM2WXNbFixnVjwC1iA0m7Vnxn8A4_MXAAMAAA"
                ],
                "deeplink_evoke": null,
                "download_start": null,
                "download_complete": null,
                "installation_start": null,
                "installation_complete": null,
                "activation": null
            },
            "video": null
        }
    ]
}
宏替换
参数名 类型
_LAT_ 手指按下时的纬度坐标
_LON_ 手指按下时的经度坐标
_DOWN_X_ 手指按下时的横坐标,屏幕坐标
_DOWN_Y_ 手指按下时的纵坐标,屏幕坐标
_UP_X_ 手指松开时的横坐标,屏幕坐标
_UP_Y_ 手指松开时的纵坐标,屏幕坐标
_OFFSET_X_ 手指按下时的横坐标,广告 view 上的相对坐标,以广告左上角为原点,不是屏幕的坐标
_OFFSET_Y_ 手指按下时的纵坐标,广告 view 上的相对坐标,以广告左上角为原点,不是屏幕的坐标
_OFFSET_UP_X_ 手指松开时的横坐标,广告 view 上的相对坐标,以广告左上角为原点,不是屏幕的坐标
_OFFSET_UP_Y_ 手指松开时的纵坐标,广告 view 上的相对坐标,以广告左上角为原点,不是屏幕的坐标
_TIME_START_ 手指按下时的时间戳(十三位,毫秒)
_TIME_END_ 手指松开时的时间戳(十三位,毫秒)
_TIME_TEN_START_ 手指按下时的时间戳(十位,秒)
_TIME_TEN_END_ 手指松开时的时间戳(十位,秒)
_CLICKID_ 广点通宏替换参数
广点通类下载广告说明
  • 如果action=3,代表下载类广告需要对 url 链接地址进行宏替换处理,宏替换处理完成后, 需要 get 请求 url 链接地址地址,返回结果为 json,内容如下,从 json 中提取真实下载 dstlink,如下格式:
    {
      "data":{
          "clickid":"xxxxxxxxxxxxx",
          "dstlink":"http://xxx.com/xxx/xxx.apk"
      },
      "ret":0
    }
    
名称 类型 是否必填(Y/N) 描述
clickid string Y 点击 ID,需要缓存下来,用于后续下载,安装,激活类转化上报链接中${CLICKID} 的宏替换
dstlink string Y 目标地址,即 apk 下载地址
ret int Y 错误码,0 表示返回正常,否则表示错误