[TOC]
## **更新日志**
| 版本 | 更新时间 | 修订内容 |
| --- | --- | --- |
| 1.2.0 | 2021-01-20 | 1、添加deeplink点击上报事件<br />2、跑OPPO需要相对坐标和绝对坐标，跑vivo只需要相对坐标 |
| 1.2.1 | 2021-03-26 | 1、删除参数 img_type<br />2、添加参数 caid |
| 1.3.0 | 2021-04-09 | 1、新增广点通广告 |
| 1.3.1 | 2021-06-03 | 1、 新增参数support_universal、os_update_time、os_startup_time、phone_name、phone_name、sys_memory、sys_disksize、hardware_machine、country、language、timezone、hms_ver、hwag_ver|
| 1.3.2 | 2021-09-02 | 1、新增参数 boot_mark、update_mark |
| 1.3.3 | 2021-09-03 | 1、添加返回字段is_gdt, 修改广点通预算输出方式 |
| 1.3.4 | 2021-09-09 | 1、新增参数 ali_aaid, iOS跑阿里预算必填|
| 1.3.5 | 2021-10-08 | 1、删除宏\_\_DOWN_TIME__、\_\_UP_TIME__、\_\_SHOW_TIME__、\_\_CLICK_TIME__<br>2、新增宏请求广告位宽高\_\_REQ\_WIDTH\_\_、\_\_REQ\_HEIGHT\_\_；<br>广告展示区域坐标：\_\_DISPLAY\_LUX\_\_、\_\_DISPLAY\_LUY\_\_、\_\_DISPLAY\_RDX\_\_、\_\_DISPLAY\_RDY\_\_；<br>广告按钮区域坐标：\_\_BUTTON\_LUX\_\_、\_\_BUTTON\_LUY\_\_、\_\_BUTTON\_RDX\_\_、\_\_BUTTON\_RDY\_\_；<br>设备参数信息：\_\_MAC\_M\_\_、\_\_MAC\_MS\_\_、\_\_IMEI\_M\_\_、\_\_ANDROIDID\_\_、\_\_ANDROIDID\_M\_\_；<br>视频时间：\_\_VIDEO\_TIME\_\_、\_\_BEGIN\_TIME\_\_、\_\_END\_TIME\_\_|
| 1.3.6 | 2021-11-25 | 1、添加fallback\_type返回字段 |
| 1.3.7 | 2022-01-04 | 1、新增参数 installed |
| 1.3.8 | 2022-06-15 | 1、添加广点通唤醒广告处理方式 |
| 1.4.0 | 2022-11-25 | 1、新增参数api_version、count,新增响应字段Ad.id<br>2、响应字段data由对象改为数组对象(为了兼容，参数带api_version时生效) |
| 1.4.1 | 2022-12-12 | 1、新增小程序响应字段applet_id、applet_path、applet_appid，interaction_type=3|
| 1.4.2 | 2023-1-13 | 1、新增逻辑像素宏|
| 1.4.3 | 2023-4-23 | 1、新增响应字段ua|
| 1.4.4 | 2023-4-25 | 1、新增响应字段clk_time、over_time<br /> 2、新增参数bidfloor、响应字段price、价格宏__LW_BID_PRICE__|
| 1.4.5 | 2023-5-18 | 1、新增广告交互方式宏_\_SLD__|
| 1.4.6 | 2024-5-24 | 1、新增响应字段应用商店直投地址: market_url |
| 1.4.7 | 2024-11-19 | 1、修改请求字段 platform <br />2、增加下载六要素字段:<br /> app_version、 privacy_url 、 perm_url 、 perm_content、developer、feature_url、 size|
| 1.48 | 2024-12-06 | 1、增加请求字段 caids <br />2、删除请求字段: caid<br /> |
## **接入说明**
本文档定义了广告平台接入协议，便于媒体实现快速接入。
接入方务必详细阅读对接流程及连接方式，避免对接过程中出现问题。
> 正式对接时，媒体方需要向 BlueMobi 运营人员申请联调地址和代码位ID；
## **开发原则**
1. POST 方式，参数值以 UTF-8 编码，请使用 json/application作为 Content-Type，<span style="color:red;"> **请使用长连接请求**</span>。
2. 通过 API 请求到的广告内容，请及时展现给终端用户，不要缓存，不要同一广告展现多次，这样广告服务会将该点击判为作弊，反而使得开发者收入降低。
3. 开发者在广告请求时应尽可能多填写参数，这样广告服务可以配到更相关、用户更喜欢的广告， 能够提升用户点击率，从而提高开发者收入。但是如果开发者本身获取不到可选参数，请开发者不要随便填写可选字段，这样反而可能造成配到不相关广告，降低点击率，影响开发者收入。总之，对于可选字段，开发者应该尽最大可能填写准确可信的值。
4. 请求广告时，若从服务器发起，必须使用 ip 参数传入用户原始 IP 地址。
5. 展示上报和点击上报必须从客户端发起，禁止通过第三方服务器发起，以免被判定为作弊。
6. 请求和上报 HTTP 请求中的 User-Agent 请设置成客户端浏览器默认 User-Agent 值，不允许自定义 User-Agent, 以免被判定为作弊。请求到的广告如果超过半小时，展示就不用上报了
7. **请求和上报的ua, ip要保持一致， 宏替换尽量替换，以免过滤**
8. <span style='color:red;'>**所有广告进入落地页或者进行上报时，请求头如果在x-request-with、ua、cookie等中携带包名，需要去掉。示例: {"x-requested-with":"com.baidu.video"}**</span>
## **请求参数**
| 字段 | 类型| 是否必填 | 备注 |
| --- | --- | --- | --- |
| api_version | String | 是| API版本，当前版本号1.4.0|
| app_name | String | 是| 应用名称|
| app_version | String | 是| 应用版本,来源 于 manifest 的 versionName ，而不是versionCode如3.5.6|
| app_version_code | Int | 是| 应用版本号,来源于 manifest 的 versionCode。如 119|
| pkg_name | String | 是| 应用包名|
| platform | Int | 是| <span style="color:red;">平台：<br /> 0 - 未知<br />1 - 安卓<br /> 2 - IOS <br /> 3 - iPad <br />9 - 其他</span>|
| make | String | 是| 设备制造商，例如 OPPO|
| model | String | 是| 设备硬件型号，例如 PGCM10|
| brand | String | 是| 手机品牌,例如 OPPO|
| hwv | String | 推荐| 硬件型号版本，例如 iPhone 中的 7S，默认值："unkown"|
| os | String | 是| 操作系统，Android 或 iOS 字符串，注意大小写|
| os_version | String | 是| 系统版本，示例：7.0|
| osapilevel | Int | 是|安卓系统版本系统级别，示例：24。 av >= 29时，视为安卓系统为 Android Q 及以上|
| android_id | String | 是| Android ID|
| auidmd5 | String | 是| Android ID的MD5值|
| auidsha1 | String | 是| Android ID的sha1值|
| imei | String | 是| Android 系统必填，Android手机设备的imei|
| imeimd5 | String | 是| Android 系统必填，Android手机设备的imei的MD5值|
| imeisha1 | String | 是| Android 系统必填，Android手机设备的imei的sha1值|
| meid | String | 否| 手机设备的meid号|
| imsi | String | 否| 国际移动用户识别码|
| oaid | String | 是 | 广告标识符，安卓10以上必填|
| idfa | String | 是| IOS系统必填，原生大写|
| idfamd5 | String | 否| idfa md5|
| idfv | String | 是| IOS系统必填|
| idfvmd5 | String | 否| idfv md5|
| openudid | String | 是| IOS系统必填,设备识别码
| caids | Object Array| 否 | ios14以上**获取不到idfa时必传** 广协目前有多个caid版本，广告源按需获取。示例如下<br /> [{"id": "eeac4a69edbbe8fd373e62d838f8752d","version": "20220111"},{"id": "daad7cca70fe29d9e8c2a94a02eea04b","version": "20230330"}] |
| ip | String | 是| IP地址|
| ipv6 | String | 否| IPv6地址|
| ua | String | 是| 客户端 user-agent|
| mac | String | 是| 客户端mac地址，保留原始值|
| macmd5 | String | 是| 32位小写md5加密mac|
| density | String | 是| 屏幕密度，比例值（dpi/160） eg: 1.5 |
| ppi | Int | 是| 像素密度，表示每英寸的像素数。eg:401 |
| dpi | Int | 是| 像素点密度，表示每英寸的点数。eg:240 |
| screen_width | Int | 是| 屏幕的宽度|
| screen_height | Int | 是| 屏幕的高度|
| screen_orient | Int | 是| 屏幕的方向：<br /> 1 - 竖屏<br /> 2 - 横屏|
| app_store_version | String | 否 | 样例:oppo:5500,vivo:10700 手机自带的应用商店的版本（OV广告不能为空）,包括华为ag版本号等 |
| rom_version | String | 否 | 手机的ROM版本号（OV广告不能为空） |
| net_type | Int | 是| 客户端网络类型:<br />0.unkown<br />1.wifi<br />2.2G<br />3.3G<br />4.4G<br />5.5G|
| carrier | Int | 是| 运营商类型：<br />0. 未知运营商<br />1.中国移动<br />2.中国联通<br />3.中国电信<br />4.其他运营商|
| bssid | String | 推荐|无线网 ssid 名称|
| wifi_mac | String | 推荐|wifi 路由的 mac 地址|
| iccid | String | 否| Sim卡的序号|
| mnc | String | 否| 基站MNC|
| mcc | String | 否| 基站MCC|
| serialno | String | 是 | 系统设备序列号（获取不到需要报备）|
| ali_aaid| String | 否 | 阿里巴巴匿名设备标识，需集成阿里SDK 获取，阿里预算必填，具体查看附件。 |
| boot_mark | String | 是 | 系统启动标识，原值传输，取值参见附件文档，示例 iOS:：1623815045.970028，Android：ec7f4f33-411a-47bc-8067-744a4e7e0723 |
| update_mark | String | 是 | 系统更新标识，原值传输，取值参见附件文档，示例 iOS：1581141691.570419583， Android：1004697.709999999 |
| os_birth_time | String | 是 | iOS必传，系统初始化时间 |
| os_compiling_time | String | 是 | iOS必传， 系统编译时间 |
| os_update_time | String | 是 | iOS必传，系统最近一次更新时间，单位：秒（保留6位小数）示例："1595214620.383940" |
| os_startup_time | String | 是 | iOS必传， 系统最近一次启动时间, 秒级时间戳,（保留整数） 示例："1600607108" |
| phone_name | String | 是 | 设备名称<br>例如：张三的 iPhone |
| phone_name_md5 | String | 是 | 设备名称md5值 |
| sys_memory | String | 是 | 系统内存，单位字节 |
| sys_disksize | String | 是 | 硬盘容量，单位字节<br>例如：63900340224 |
| cpu_num | String | 是 | 设备的 cpu 核心数量 |
| hardware_machine | String | 是 |设备machine值，示例:"iPhone10.3" |
| hardware_model | String | 是 | 设备model值示例:“D22AP",仅限iOS设备 |
| country | String | 否 | 国家编码（ISO-3166-1/alpha-2）例如：CN |
| language | String | 否 | 设备语言（ISO-639-1/alpha-2）例如：zh |
| timezone | String | 否 | 系统所在时区例如：Asia/Shanghai |
| hms_ver| String | 条件必填 | 华为安卓设备的 HMS Core的版本号，保留原始值。华为手机必填 |
| hwag_ver| String | 条件必填 | 华为安卓设备的 AG（应用市场）的版本号，保留原始值。华为手机必填 |
| sys_ui_ver| String | 条件必填 | 系统UI版本，保留原始值。如小米设备的 MIUI的版本号，华为、OV、魅族等设备版本号 |
| gps_type | Int | 是| 坐标类型。<br />0：未知；<br />1= WGS84(全球卫星定位系统坐标系)；<br />2= GCJ02（国家测绘局坐标系）；<br />3= BD09（百度坐标系）；|
| longitude | Double | 是| 经度，默认值： 0|
| latitude | Double | 是| 纬度，默认值：0|
| gps_ts | Int | 是| 获取 gps 位置时的时间戳,单位：秒|
| ad_width | Int | 是| 广告位宽度，单位为像素|
| ad_height | Int | 是| 广告位高度，单位为像素|
| support_deeplink | Int | 是| 是否支持deeplink:<br />0.不支持<br />1.支持|
| support_universal | Int | 是| 是否支持universal link:<br />0.不支持<br />1.支持|
| installed | []String | 否 | 从应用列表中筛选已安装的应用包名进行上传，如<br />["com.sina.news","com.kuaishou.nebula"] |
| count | Int | 否 | 广告数量，默认1，预留字段，部分预算有效|
| bidfloor| Int | 否 | 底价，单位分，部分预算有效|
> 参数请尽量获取，实在无法获取的可暂时填写模拟默认值（0 or ""等）模拟测试，有问题再与技术协调
## **广告响应**
### 响应参数
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| code | Int | 是 | 响应状态码，0=正常, 1=无填充，其他请看msg提示 |
| msg | String | 是 | 响应提示消息|
| data | []Ad **Object** | 否 | 广告信息 |
| unique| String | 是 | 请求唯一标识符 |
### Ad
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| id | String | 否 | 曝光id，每个广告唯一 |
| title | String | 否 | 主标题 |
| desc | String | 否 | 描述 |
| price| Int | 否 | 投放出价，单位分，部分预算有效|
| ad_width | Int | 否 | 广告宽度|
| ad_height | Int | 否 | 广告高度 |
| ad_logo | String | 否 | 广告图标 |
| imgs | []String | 否 | 图片地址数组 |
| fallback_type | Int | 否 | deeplink 退化类型，应用未安装时如何处理，默认0 <br />0 - 浏览器打开 <br /> 1 - 下载应用 |
| interaction_type | Int | 是 | 广告操作行为：<br />0 - 落地页 <br />1 - 下载 <br />2 - 唤醒<br /> 3 - 小程序广告 |
| ad_type | Int | 否 | 广告类型：<br />1 - Banner<br />2 - 开屏<br />3 - 插屏<br />4 - 信息流 <br />5 - 激励视频 |
| is_gdt | Int | 否 | 是否广点通:<br />0 - 不是<br /> 1 - 是 |
| replace | Int | 是 | 是否需要宏替换:<br />0 - 不需要<br /> 1 - 需要 |
| deeplink | String | 否 | Deeplink地址 |
| market_url| String | 否 | 应用商店直投schema地址,用于直接打开应用商店详情页 |
| clk | String | 是 | 落地页/点击行为地址，优先级: <span style="color:red;"> deeplink > market_url > clk </span> |
| clk_time | Int| 否 | 点击事件触发的时间，单位：秒，距离曝光的时间。不传或0默认正常处理后续广告行为 |
| over_time | Int| 否 | 超时时间，单位秒，当因灭屏导致程序中断时间超过该设置时间时，后续广告行为不处理。不传或0默认不处理超时，正常处理后续广告行为 |
| **applet_id** | String | 否 | ⼩程序原始ID，格式:gh\_xxxxxxx |
| **applet_path** | String | 否 | ⼩程序⻚⾯的可带参路径，schema |
| **applet_appid** | String | 否 | ⼩程序id，格式:wxexxxxxxx |
| ua| String | 否 | 后续上报事件、访问素材以及落地页URL需要使用的UA，没有时默认传客户端ua |
| event | Event **Object** | 是 | 事件行为,使用GET请求上报 |
| video | Video **Object**| 否 | 激励视频信息 |
| video_event| VideoEvent **Object** | 否 | 激励视频事件行为,使用GET请求上报 |
| appinfo| App **Object** | 是 | App信息 |
### Event
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| show | []String | 是 | 展示跟踪链接数组，对接广告位客户端需要获取show里的所有链接进行逐条上报。上报时,http header头中需要增加User-Agent属性，下同！ |
| click | []String | 是 | 点击跟踪链接数组，对接广告位客户端需要获取click 里的所有链接进行逐条上报。 |
| start_down| []String | 否 | 开始下载上报数组|
| down_done| []String | 否 | 下载完成上报数组 |
| start_install| []String | 否 | 开始安装上报数组 |
| install_done| []String | 否 | 安装完成上报数组 |
| open_app_success | []String | 否 | deeplink 打开成功后上报数组 |
| open_app_false | []String | 否 | deeplink 打开失败后上报数组 |
| open_app_click | []String | 否 | deeplink被点击(尝试唤起)，如果为空，无需上报 |
| active_app | []String | 否 | 安装后激活打开App后上报数组 |
### Video
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| url | String | 是 | 视频地址 |
| cover| String | 否 | 视频素材封面地址 |
| desc | String | 否 | 广告文本描述，如点击下载查看详情等 |
| width | Int| 否 | 视频宽度，像素 |
| height | Int| 否 | 视频高度，像素 |
| duration| Float | 否 | 视频时长（秒） |
| end_show_type | Int | 否 | 视频播放结束显示尾帧类型:<br />空/0：没有 ;<br />1：图片url; <br /> 2：html页面 ; <br />3：html url |
| end_show_value | String | 否 | 视频播放结束显示尾帧值，存放videoEndShowType对应类型的数据 |
| html_show_tracking | []String | 否 | 跳转类广告落地页展示上报链接 |
| html_click_tracking | []String | 否 | 跳转类广告落地页点击上报链接 |
| html_close_tracking | []String | 否 |跳转类广告落地页关闭后进行的上报链接 |
### VideoEvent
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| start_tracks| []String | 否 | 视频开始播放追踪 url 数组 |
| click_tracks| []String | 否 | 视频播放过程中点击追踪 url 数组 |
| complete_tracks| []String | 否 | 视频播放完成追踪 url 数组 |
| skip_tracks| []String | 否 | 视频跳过播放追踪 url 数组 |
| stop_tracks| []String | 否 | 视频暂停播放追踪 url 数组 |
| unstop_tracks| []String | 否 | 视频解除暂停播放追踪 url 数组 |
| mute_tracks| []String | 否 | 视频静音追踪 url 数组 |
| unmute_tracks| []String | 否 | 视频取消静音追踪 url 数组 |
| play_first_quartile_tracks| []String | 否 | 视频播放 1/4 追踪 url 数组 |
| play_midpoint_tracks| []String | 否 | 视频播放 1/2 追踪 url 数组 |
| play_third_quartile_tracks| []String | 否 | 视频播放 3/4 追踪 url 数组 |
| close_tracks| []String | 否 | 视频关闭 追踪 url 数组 |
### App
| 字段 | 类型 | 是否必填 | 备注 |
| --- | --- | --- | --- |
| app_name| String | 否 | App名称 |
| package_name| String | 否 | 包名 |
| app_version| String | 否 | 应用版本 |
| privacy_url | String | 否 | 应用隐私链接 |
| perm_url | String | 否 | 应用权限链接 |
| perm_content | String | 否 | 应用权限内容 |
| developer| String | 否 | 应用开发者 |
| feature_url| String | 否 | 应用功能介绍链接 |
| size| Int| 否 | 应用大小 |
## Interaction_type 值说明
| 数值 | 说明 |
| --- | --- |
| 0 | 落地页是页面，直接调用浏览器打开clk，展示上报 show，点击上报 click |
| 1 | 点击后落地页clk是应用下载地址(若deeplink有值，先使用原生方法处理deeplink并单独触发clk点击检测)，走 event 对象的下载流程，依次展示上报 show，点击上报 click，开始下载上报 start_down，下载完成上报 down_done ，开始安装上报 start_instal，安装完成上报 install_done，激活上报 active_app |
| 2 | 唤醒处理，走唤醒流程，展示上报 show，点击上报 click，唤醒成功 open_app_success，唤醒失败 open_app_false |
1. 先根据图片和广告标题之类的拼揍出一个广告页面，页面出来之后逐条上报 show里的URL
2. 当用户点击后逐条上报 click 的 url，点击后先判断deeplink如果有值则访问 deeplink(如果 deeplink 有宏需要替换也得处理),拉起应用，此时上报 open_app_success 里的所有 url。如果失败，则上报 open_app_false 里的所有 url，并且根据fallback_type值判断clk链接交互方式，默认以webview浏览器打开clk
### 点击广告流程
部分广告仅部分上报流程，为空则不上报，请注意判别，结合上下文进行合理操作。
### **优先级: deeplink > market_url > clk**
## 宏替换
>推荐**左右两条下划线，中间一条下划线**
使用$$、%%等特殊符号会存在兼容问题！！！从而影响上报统计，望知悉！！！
<table>
<tr>
<th>宏</th>
<th colspan="2">说明</th>
</tr>
<tr>
<td>__REQ_WIDTH__</td>
<td rowspan="6">广告位宽高</td>
<td>请求时广告位宽度</td>
</tr>
<tr>
<td>__REQ_HEIGHT__</td>
<td>请求时广告位高度</td>
</tr>
<tr style="color:red;">
<td>__WIDTH__</td>
<td>实际广告位宽度，单位为物理像素</td>
</tr>
<tr style="color:red;">
<td>__HEIGHT__</td>
<td>实际广告位高度，单位为物理像素</td>
</tr>
<tr style="color:red;">
<td>__DP_WIDTH__</td>
<td>实际广告位宽度，单位为逻辑像素</td>
</tr>
<tr style="color:red;">
<td>__DP_HEIGHT__</td>
<td>实际广告位高度，单位为逻辑像素</td>
</tr>
<tr>
<td>__DISPLAY_LUX__</td>
<td rowspan="4">广告展示区域坐标（坐标定义：以屏幕左上角坐标为原点）</td>
<td>左上角横坐标</td>
</tr>
<tr>
<td>__DISPLAY_LUY__</td>
<td>左上角纵坐标</td>
</tr>
<tr>
<td>__DISPLAY_RDX__</td>
<td>右下角横坐标</td>
</tr>
<tr>
<td>__DISPLAY_RDY__</td>
<td>右下角纵坐标</td>
</tr>
<tr style="color:red;">
<td>__DOWN_X__</td>
<td rowspan="4">点击相关 1（绝对坐标定义：以屏幕左上角坐标为原点，单位物理像素）</td>
<td>点击时横坐标</td>
</tr>
<tr style="color:red;">
<td>__DOWN_Y__</td>
<td>点击时纵坐标</td>
</tr>
<tr style="color:red;">
<td>__UP_X__</td>
<td>弹起时横坐标</td>
</tr>
<tr style="color:red;">
<td>__UP_Y__</td>
<td>弹起时纵坐标</td>
</tr>
<tr style="color:red;">
<td>__DOWN_OFFSET_X__</td>
<td rowspan="4">点击相关 2（相对坐标定义：以广告位左上角为原点，单位物理像素）</td>
<td>点击时横坐标</td>
</tr>
<tr style="color:red;">
<td>__DOWN_OFFSET_Y__</td>
<td>点击时纵坐标</td>
</tr>
<tr style="color:red;">
<td>__OFFSET_X__</td>
<td>弹起时横坐标</td>
</tr>
<tr style="color:red;">
<td>__OFFSET_Y__</td>
<td>弹起时纵坐标</td>
</tr>
<tr style="color:red;">
<td>__DP_DOWN_X__</td>
<td rowspan="4">点击相关 3（相对坐标定义：以广告位左上角为原点，单位逻辑像素）</td>
<td>点击时横坐标</td>
</tr>
<tr style="color:red;">
<td>__DP_DOWN_Y__</td>
<td>点击时纵坐标</td>
</tr>
<tr style="color:red;">
<td>__DP_UP_X__</td>
<td>弹起时横坐标</td>
</tr>
<tr style="color:red;">
<td>__DP_UP_Y__</td>
<td>弹起时纵坐标</td>
</tr>
<tr>
<td>__BUTTON_LUX__</td>
<td rowspan="4">广告 按钮 区域坐标（坐标定义：以 屏 幕 左 上角坐标为原点）</td>
<td>左上角横坐标</td>
</tr>
<tr>
<td>__BUTTON_LUY__</td>
<td>左上角纵坐标</td>
</tr>
<tr>
<td>__BUTTON_RDX__</td>
<td>右下角横坐标</td>
</tr>
<tr>
<td>__BUTTON_RDY__</td>
<td>右下角纵坐标</td>
</tr>
<tr>
<td>__READY_TIME__</td>
<td colspan="2">所有⼴告素材下载完成时的当前时间戳，精确到毫秒(13 位)</td>
</tr>
<tr style="color:red;">
<td>__TS__</td>
<td colspan="2">执行时间戳秒级</td>
</tr>
<tr style="color:red;">
<td>__MTS__</td>
<td colspan="2">执行时间戳毫秒级替换 13位</td>
</tr>
<tr>
<td>__EVENT_TIME_START__</td>
<td colspan="2">事件开始时 13位时间戳，单位毫秒</td>
</tr>
<tr>
<td>__EVENT_TIME_END__</td>
<td colspan="2">事件结束时 13位时间戳，单位毫秒</td>
</tr>
<tr>
<td>__LONGITUDE__</td>
<td colspan="2">经度，没有则替换为 0</td>
</tr>
<tr>
<td>__LATITUDE__</td>
<td colspan="2">纬度，没有则替换为 0</td>
</tr>
<tr>
<td>__UA__</td>
<td colspan="2">UserAgent,客户端 UA,需要 URLEncode</td>
</tr>
<tr>
<td>__IP__</td>
<td colspan="2">客户端IP地址</td>
</tr>
<tr>
<td>__MAC__</td>
<td colspan="2">设备 mac 地址</td>
</tr>
<tr>
<td>__MAC_M__</td>
<td colspan="2">设备的 mac 地址，字符串，保留分隔符“:”，转大写，然后 MD5 加密</td>
</tr>
<tr>
<td>__MAC_MS__</td>
<td colspan="2">设备的 mac 地址，字符串，去除分隔符“:”，转大写，然后 MD5 加密</td>
</tr>
<tr>
<td>__IMEI__</td>
<td colspan="2">IMEI，Android 设备的 IMEI 号</td>
</tr>
<tr>
<td>__IMEI_M__</td>
<td colspan="2">Android 设备的 IMEI 号,MD5 加密</td>
</tr>
<tr>
<td>__ANDROIDID__</td>
<td colspan="2">Android ID</td>
</tr>
<tr>
<td>__ANDROIDID_M__</td>
<td colspan="2">Android ID,MD5 加密</td>
</tr>
<tr>
<td>__OAID__</td>
<td colspan="2">Android 广告标识符</td>
</tr>
<tr>
<td>__IDFA__</td>
<td colspan="2">idfa，iOS 设备的 IDFA</td>
</tr>
<tr>
<td>__CLICKAREA__</td>
<td colspan="2">点击区域：1-广告素材；2-按钮</td>
</tr>
<tr>
<td>__CLICK_ID__</td>
<td colspan="2">点击唯一ID</td>
</tr>
<tr>
<td>__DP_REASON__</td>
<td colspan="2">调起失败原因，调起失败时必填：1-被 拦截，2-应用未安装，3-调起异常</td>
</tr>
<tr>
<td>__DP_RESULT__</td>
<td colspan="2">deeplink 调起结果：0-成功，1-失败</td>
</tr>
<tr>
<td>__VIDEO_TIME__</td>
<td colspan="2">视频总时长(s)</td>
</tr>
<tr>
<td>__BEGIN_TIME__</td>
<td colspan="2">视频播放开始时间(s)</td>
</tr>
<tr>
<td>__END_TIME__</td>
<td colspan="2">视频播放结束时间(s)</td>
</tr>
<tr>
<td>__PROGRESS__</td>
<td colspan="2">视频⼴告播放的进度，单位秒</td>
</tr>
<tr>
<td>__PROGRESS_MS__</td>
<td colspan="2">视频⼴告播放的进度，单位毫秒</td>
</tr>
<tr>
<td>__RATE__</td>
<td colspan="2">视频⼴告播放的进度，百分比</td>
</tr>
<tr>
<td>__LW_BID_PRICE__</td>
<td colspan="2">曝光价格原值，取整，单位分，竞价必须！</td>
</tr>
<tr>
<td>__SLD__</td>
<td colspan="2">广告交互方式:<br> 0 - 常规触屏点击<br> 1 - 滑动点击<br> 2 - 摇一摇<br> 3 - 自定义手势<br> 5 - 扭一扭<br> 6 - 擦除</td>
</tr>
</table>
> 所有上报链接里都可能含有上面宏，都需要替换坐标，特别注意，落地页 clk 也可能含有坐标宏需要替换
比如 click 里的一条 url 包含“\_\_DOWN_X_\_ ”这个字符，那你就得用你按下时的坐标比如210，去替换这个值
## 广点通广告处理
仅针对于**唤醒类**预算(即 deeplink有值时)，且**is_gdt** 值为 1 时，执行正常唤醒操作；当唤起目标app失败时，则使用点击响应data JSON对象的**dstlink**进行跳转；
仅针对于**下载类**预算(即 Interaction\_type=1)，且**is_gdt** 值为 1 时：需要 http get 二次请求 clk，以便获取到最终的下载地址以及后续下载、安装监测需要用clickid 替换里面的\_\_CLICK_ID__ 的字段。
二次请求的响应格式如下：
```
{
"ret":0,
"data":{
"dstlink":"http://xxx/xxx.apk",
"clickid":"xxxxxxxxxxx"
}
}
```
广点通坐标替换处理点：
1、广告位相对坐标 \_\_DOWN_OFFSET_X\__ 、\_\_DOWN_OFFSET_Y\__、 \_\_OFFSET_X\__、 \_\_OFFSET_Y\__ 、\_\_WIDTH__、\_\_HEIGHT__这些值必须替换
2、替换的坐标不能超出广告点击区域，例如（广告位的实际宽高：600*300,那点击的x和y一定在600和300里面）
3、宏替换在**clk**中有，点击上报链接**click**中也有，点击上报链接中的宏也都要替换，替换的值和**clk**中的一样。
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| ret | Int | 0 表示返回值正常，当 ret 返回错误值时，不打开落地页，不发送后续监测上报 |
| dstlink | String | 真正的下载地址，客户端解析 json 后直接请求该地址开始下载 app。 |
| clickid | String | 点击 ID。需缓存下来，用于后续点击、下载事件上报（转化上报）。替换上报中的宏变量\_\_CLICK_ID__|
## 请求示例
```
{
"api_version": "1.4.0",
"app_name": "抖音短视频",
"pkg_name": "com.ss.android.ugc.aweme",
"app_version": "5.6.0",
"make": "Oppo",
"brand": "Oppo",
"model": "Oppor15",
"hwv": "5s",
"android_id": "83ae257b377746ec",
"auidmd5": "523AB7C8EA18A674C4A085E354818AAB",
"auidsha1": "bc4520537f6e32940c2e291b0a999bf079c17376",
"imei": "867905025513807",
"imeimd5": "B7B46DA7A31349518CD8E87857DDEC8A",
"imeisha1": "69db2ef0feb8048321b8a14cd2888e42f7f9771d",
"imsi": "7512a3c480f43980dc1c45738c078921",
"ua": "Mozilla/5.0 (Linux; Android 8.1.0; M1816 Build/O11019; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/65.0.3325.109 Mobile Safari/537.36",
"mac": "90:f0:52:40:c5:a1",
"net_type": 1,
"density": 1.5,
"screen_width": 1080,
"screen_height": 1920,
"dpi": 326,
"ppi": 441,
"platform": 1,
"os": "Android",
"os_version": "10.1",
"osapilevel": 8.0,
"ip": "223.104.65.150",
"screen_orient": 1,
"serialno": "008d4305e9ab2653ce4ce86704f3cf3f",
"carrier": 1,
"latitude": 0,
"longitude": 0,
"iccid": "008d4305e9ab2653ce4ce86704f3cf3f",
"bssid": "",
"pkgs": "",
"mnc": "",
"mcc": "",
"oaid": "846359299220",
"ad_width": 350,
"ad_height": 150,
"support_deeplink": 1,
"installed": [
"com.kuaishou.nebula",
"com.sina.news",
"com.smile.gifmaker",
"com.ss.android.ugc.aweme.lite",
"com.ss.android.ugc.aweme",
"com.quark.browser",
"com.wuba",
"com.dragon.read",
"com.baidu.searchbox",
"com.anjuke.android.app",
"com.eg.android.AlipayGphone",
"com.UCMobile",
"com.qqjh.easyclean",
"cn.emagsoftware.gamehall",
"com.tencent.qqlivekid",
"com.tencent.qqlive",
"com.tencent.map"
]}
```
## 响应数据
```
{
"code": 0,
"msg": "OK",
"unique": "30f3cdb46c61f4",
"data": [{
"title": "开屏测试广告",
"desc": "",
"ad_width": 720,
"ad_height": 1280,
"clk": "http://download.alicdn.com/wireless/taobao4android/latest/702757.apk",
"deeplink": "",
"replace": 0,
"interaction_type": 1,
"imgs": [
"http://cdn.cloudmob.xyz/img/pg_20200416105713.jpg"
],
"event": {
"show": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=show"
],
"click": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=click"
],
"start_down": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=start_down"
],
"down_done": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=down_done"
],
"start_install": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=start_install"
],
"install_done": [
"http://ssp2.com/media/ads_report?&action=install_done"
],
"open_app_success": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=open_app_success"
],
"open_app_false": [
"http://ssp2.com/media/ads_report?action=open_app_false"
],
"active_app": [
"http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=active_app"
]
},
"appinfo": {
"app_name": "",
"package_name": ""
}
}]
}
```
## 激励视频响应示例
```
{
"code": 0,
"msg": "OK",
"unique": "AUdisTexOhjpjDgr1611041011",
"data": [{
"title": "",
"desc": "这是什么神仙游戏，挂机就能领红包，提现秒到账！",
"ad_width": 0,
"ad_height": 0,
"clk": "http://down-ddz.734399.com/download/shandianapi/shandian3-awddz-release0529.apk",
"ad_type": 5,
"interaction_type": 1,
"replace": 1,
"deeplink": "",
"imgs": [
],
"event": {
"show": [
"http://ssp.com/media/ads_report?"
],
"click": [
"http://ssp.com/media/ads_report?"
],
"start_down": [
"http://ssp.com/media/ads_report?"
],
"down_done": [
"http://ssp.com/media/ads_report?"
],
"start_install": [
"http://ssp.com/media/ads_report?"
],
"open_app_success": []
},
"video": {
"url": "http://static.wannuosili.com/material/1610957675.685468_46_tmpb8huo0kk.webm",
"width": 720,
"height": 1280,
"size": 0,
"duration": 34
},
"video_event": {
"start_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"click_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"complete_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"skip_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"mute_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"unmute_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"play_first_quartile_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"play_midpoint_tracks": [
"https://adx.test.com/ssp/report?t=v"
],
"play_third_quartile_tracks": [
"https://adx.test.com/ssp/report?t=v"
]
},
"appinfo": {
"app_name": "",
"package_name": "com.awpanda.pandaddz"
}
}]
}
```
## 返回状态码
| 状态码 | 说明 |
| --- | --- |
| 0 | 广告请求成功，有广告填充 |
| 1 | 无广告填充！ |
| 其他 | 其他错误 |
## 附件
### 1.参数boot\_mark和update\_mark
**boot\_mark iOS参考代码**
**boot\_mark Android参考代码**
**update\_mark iOS参考代码**
**update\_mark Android参考代码**
### 2.阿里aaid参数集成
[查看ali_aaid集成方式](http://ssp.ibluefrog.com/doc/Ali_AAID_API%E6%8E%A5%E5%85%A5%E6%96%87%E6%A1%A3_v0310.pdf)
