[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 | ## **接入说明** 本文档定义了广告平台接入协议，便于媒体实现快速接入。 接入方务必详细阅读对接流程及连接方式，避免对接过程中出现问题。 > 正式对接时，媒体方需要向 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 | 是| 平台：<br /> 0 - 未知<br />1 - 安卓<br /> 2 - IOS <br /> 3 - 其他| | 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系统必填，原生大写| | idfv | String | 是| IOS系统必填| | openudid | String | 是| IOS系统必填,设备识别码| | caid| String | 否 | 中国广告协会互联网广告标识，ios14以上填写 | | 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 | 否 | 包名 | ## 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)