Android iOS Unity JS API Media API 常见问题

腾讯联盟 API 接入文档

文档版本 修订日期 作者 修订说明
V1.0 2014-09-23 于荣彬 接口文档创建
V1.1 2015-10-29 于荣彬 更新用户标示获取加密规格
V1.2 2015-11-03 于荣彬 更新无广告返回时排查方法
V2.0 2016-03-24 沈鑫、王春辉 增加请求参数取值介绍和效果上报渠道，及接口文档模板更新
V2.1 2016-07-05 王春辉 更新请求参数填写标准，remoteip变成必填
V3.0 2017-05-11 宗周、王春辉 重构协议，不兼容历史版本。2019年6月30日之前，腾讯广告联盟对历史接口在系统服务层面保持兼容，但不再维护和支持新特性。强烈建议开发者尽快迁移到新接口。主要修改内容有：
1.规范参数名称和根据参数含义对其分组，增强协议可读性
2.完善参数描述和填写错误的影响
3.新增请求和响应示例
4.优化下载类广告点击交互处理流程：取消跳转应用详情页和直接开始下载的方式，腾讯广告联盟只返回APP下载地址，由开发者做下载交互处理
5.完善返回码列表，列出所有返回码和处理方式
V3.1 2017-12-11 宗周、张洪国、王春辉、陈雪雅 1.支持视频广告和资质通荐广告接入
2.ios系统开屏广告位支持图片宽高比为640:1136的广告
V3.2 2018-10-25 茅潇潇、李霄、杨晓磊、柳娟 1.支持应用直达广告
2.支持激励视频广告
3.支持原生三图两文类型广告
V3.3 2019-03-25 邵立杰、谢宇、柳娟、李霄、王鹤飞 1.支持headbidding
2.去除banner和插屏样式
3.开屏适配逻辑修改，全面支持9:16尺寸
V3.4 2019-09-16 茅潇潇、李霄、宗周 1.更新crt_type定义
2.完善应用直达类广告的转化上报逻辑
v3.5 2019-09-27 李宁 1.支持设备标识oaid等设备标识
2.文档线上化迁移
v3.6 2020-02-20 孟嵩、陈雪雅、周敏菲 支持部分字段
v3.7 2021-07-12 周敏菲、胡婷婷、杨瑞 增加RTB、HB相关字段说明
v3.8 2021-07-28 周敏菲、胡婷婷、杨瑞 完善RTB接入方式相关字段
v3.9 2021-09-08 韩康、杨瑞 API增加竞胜竞败上报支持

关于文档

对有APP流量变现需求但由于各种原因无法嵌入腾讯广告联盟SDK的开发者，腾讯广告联盟提供基于广告播放API的合作方式。开发者应保证获得用户授权同意，由开发者收集并向腾讯提供如下字段。本文档详细介绍了广告播放API的运营对接流程和接口协议等内容。

背景知识

名词解释

技术规范

有关标准HTTP协议，可参考 RFC2616 或 维基百科-HTTP 。有关URL编码，可参考RFC3986或维基百科-Percent-encoding。有关JSON数据格式，可参考 JSON.ORG 或 维基百科–JSON 。

对接流程

流程介绍

对接流程

前期准备：API合作以腾讯广告联盟运营人员（以下简称运营人员）邀请的方式发出，开发者在接受邀请后，需在运营人员指导下填写《API接入申请表》。

注意事项

广告播放API

腾讯广告联盟后台服务（以下简称联盟后台）通过广告播放API对外提供广告请求和数据上报服务。该API包含如下四个接口，调用流程见下文广告播放时序图。

强烈建议开发者通过后台服务请求广告。如果是想让APP直接请求广告，首选SDK接入方式，开发工作量小而且流量变现效果通常会更好。联盟后台后续可能会禁止APP直接发起广告请求。

通信方式

联盟后台与外部调用方的基础通信协议采用HTTP协议和HTTPS协议。

超时时间

不考虑网络链路（调用方与联盟后台服务器之间的传输链路）时延，对99%的请求，联盟后台能在200ms内响应（资质通荐广告在400ms内响应）。广告请求超时时间建议设置1秒；其他接口建议设置较大的超时时间，比如10秒。

编码方式

若无特殊说明，所有输入参数、返回结果的字节编码均使用UTF-8（无BOM头)。

HTTP请求

名称 必填 说明
X-Forwarded-For 是 用户设备的公网出口IPv4地址。点分字符串形式，示例：14.17.22.37。当广告请求由server发起时，该字段务必正确填写，否则将严重影响流量变现效果。
User-Agent 否 用户设备HTTP请求头中的User-Agent字段。
Referer 否 用户设备HTTP请求头中的Referer字段。

HTTP响应

广告请求接口

开屏广告位必须实时请求广告（实时是指在广告位即将展示给用户或已经展示给用户时），不允许缓存广告；其他广告位可以预请求广告并缓存起来，然后在合适的时机将广告曝光。预请求广告可能产生广告预算不足等一系列问题，从而影响流量变现效果，建议所有类型广告位实时请求广告。

广告请求接口-请求地址

广告请求接口-请求数据

请求数据定义

可选参数填写原则：1. 首先保证取值正确；2. 在取值正确的前提下尽量填写。如不能获取，或不能保证取值正确性，则不填写，以免拉低流量质量，影响变现效果。

参数名称 类型 必填 限制 说明
api_version string 是 协议版本，目前仅支持3.0及以上版本，建议使用最新版本
support_https int32 否 可能取值:
1 – 支持HTTPS并且需要HTTPS资源		 是否支持HTTPS并且需要HTTPS资源。当支持HTTPS并且需要HTTPS资源时，联盟后台保证返回的图片地址、曝光、点击、转化上报地址均使用HTTPS地址。
注意当app支持HTTPS并且需要HTTPS资源时，联盟后台对某些情况仍然可能返回HTTP资源，开发者必须能兼容处理这些情况：
1. 当请求渲染过的广告（请求参数pos.need_rendered_ad=true）时，返回的html片段中的资源地址可能是HTTP地址。
2. 点击上报时，联盟后台返回的302跳转目标地址（HTTP头部字段Location）可能是HTTP地址。
pos string 是 广告位相关信息。该参数的值是一个经过url编码的json对象，见pos JSON对象。
media string 是 媒体相关信息。该参数的值是一个经过url编码的json对象，见media JSON对象。
device string 是 用户设备相关信息。该参数的值是一个经过url编码的json对象，见device JSON对象。
network string 是 用户设备网络相关信息。该参数的值是一个经过url编码的json对象，见network JSON对象。
geo string 否 用户设备实时地理位置相关信息。该参数的值是一个经过url编码的json对象，见geo JSON对象。
名称 类型 必填 限制 说明
id int64 是 广告位ID。
width int32 是 可能填写的值见附录广告位宽和高填写逻辑，原生广告位、激励视频广告位和资质通荐广告位不填。 广告位宽。该参数在联盟后台用来选取合适尺寸的广告，不要求与用户设备上真实的广告位宽严格一致。
height int32 是 可能填写的值见附录广告位宽和高填写逻辑，原生广告位、激励视频广告位和资质通荐广告位不填。 广告位高。该参数在联盟后台用来选取合适尺寸的广告，不要求与用户设备上真实的广告位高严格一致。
ad_count int32 是 原生广告位取值不超过10；其它广告位只能填1。 请求广告数量。
last_ad_ids string 否 逗号分隔的广告id列表。 最近曝光过的广告。联盟后台会过滤掉这些广告，不填写或填写错误可能导致短时间内多次请求返回的广告重复。
channel int32 否 可能取值：见附录资质通荐垂直频道列表和资质通荐地域频道列表。资质通荐广告位必填，其他广告位不需要填写。 当前请求的频道ID。资质通荐广告位不填写或填写错误将无结果返回。
page_number int32 否 资质通荐广告位必填，其他广告位不需要填写。 当前请求的页码数。页码从1开始，不填写或填写错误可能导致资讯内容重复。
deep_link_version int32 否 可能取值:
1 - 请求应用直达广告。		 是否请求应用直达广告。当该字段填1且该媒体已开通应用直达权限时，联盟后台支持返回应用直达广告，但不是一定返回应用直达广告；其它情况下（该字段未填或填其他值或未开通应用直达权限），联盟后台只返回非应用直达广告。
max_duration int32 否 视频广告最大播放时长,单位为秒。
adx_id int32 否 API流量不适用 仅针对RTB接入方式的实时竞价流量适用，通过API接入的实时竞价流量，无需获取与填写此ID。
bid_floor int32 否 API流量不适用 仅针对RTB接入方式的实时竞价流量适用，通过API接入的实时竞价流量，无需填写此值。
名称 类型 必填 限制 说明
app_id string 是 在联盟平台创建媒体时分配的应用ID。不填写或填写错误将不返回广告。
app_bundle_id string 是 可能取值：
1. android设备：使用package name
2. ios设备：使用bundle id		 应用包名。不填写或填写错误将不返回广告。请求填写包名要与注册媒体时填写保持一致，不一致将无广告返回。
名称 类型 必填 限制 说明
os string 是 可能取值：
1. ios(小写）
2. android(小写）		 操作系统。不填将不返回广告，填写错误会影响流量变现效果。
os_version string 是 三段式或两段式版本号。如果获取不到，填写unknown(小写）。 os版本。不填将不返回广告，填写错误或填写unknown会影响流量变现效果。
model string 是 1. android设备:可调用系统接口android.os.Build.MODEL直接获得。
2. ios设备：系统接口返回值。
注意：早期版本文档要求对系统接口返回原始值做转换，映射表见附录ios设备型号取值列表。如果流量已经接入腾讯广告联盟并做了转换，可以保持现状。但映射表不再更新，对在映射表中查不到映射值的流量（ios系统新版本流量），请填系统接口返回原始值。
3. 如果获取不到，填写unknown(小写）。		 设备型号。不填将不返回广告，填写错误或填写unknown会影响流量变现效果。
manufacturer string 是 1. android设备：可调用系统接口android.os.Build.MANUFACTURER直接获得。如果获取不到，填写unknown(小写）。
2. ios设备：无需填写。		 设备厂商。安卓设备不填将不返回广告，填写错误或填写unknown会影响流量变现效果。
device_type int32 是 可能取值：
0 – 未知
1 – 手机（包括iTouch）
2 – 平板		 设备类型。不填将不返回广告，填写错误或填写unknown会影响流量变现效果。
screen_width int32 否 设备竖屏状态时的屏幕宽。取设备物理像素。
screen_height int32 否 设备竖屏状态时的屏幕高。取设备物理像素。
orientation int32 否/是（激励视频广告位） 可能取值：
0 - 竖屏
90 - 横屏		 APP横竖屏。
激励视频广告位该参数为必填。
idfa string 是 36个字符，仅限ios设备 ios设备的idfa，保留原始值。不填将不返回广告，填写错误会严重影响流量变现效果。
idfa_md5 string 是 32个字符，仅限ios设备 ios设备的idfa（如果出现字母，转为大写），取md5sum摘要，摘要小写，32位。该参数用来替补idfa，两者传其一即可，强烈建议优先填写idfa。
imei string 是 仅限安卓设备 android设备的imei，保留原始值。在能取到的情况下必须填写，不填写或填写错误会严重影响流量变现效果。
imei_md5 string 是 32个字符，仅限安卓设备 android设备的imei（如果出现字母，转为小写），取md5sum摘要，摘要小写，32位。例如：imei为100000239060471，则该参数应填写md5(100000239060471)=df895d8ed25548b603fddf94fecdd7cc。该参数用来替补imei，两者传其一即可，强烈建议优先填写imei。
android_id string 是 16个字符，仅限安卓设备 android设备的Android ID，保留原始值。在能取到的情况下必须填写，不填写或填写错误会影响流量变现效果。
android_id_md5 string 是 32个字符，仅限安卓设备 android设备的Android ID，取md5sum摘要，摘要小写。该参数用来替补android_id，两者传其一即可，强烈建议优先填写android_id。
android_ad_id string 否 36个字符，仅限安卓设备 android设备的Android Advertising ID，保留原始值。大陆大部分设备无法获取，在保证取值正确有效的前提下填写，后续腾讯广告联盟会将其用于定向优化。
oaid string 是 仅限安卓设备 android设备的OAID，保留原始值，部分厂商部分安卓系统版本提供，MSA官方链接为：http://msa-alliance.cn/
aid_ticket string 是 仅限安卓设备 腾讯提供的ID获取工具获取的设备标识aid票据，保留原始值，id获取工具预计10月份发布
taid_ticket string 是 仅限安卓设备 腾讯提供的ID获取工具获取的设备标识taid票据，保留原始值，id获取工具预计10月份发布
device_start_sec string 是 仅限iOS设备 设备启动时间（秒）
country string 是 仅限iOS设备 国家
language string 是 仅限iOS设备 语言
device_name_md5 string 是 仅限iOS设备 设备名称的MD5值
hardware_machine string 是 仅限iOS设备 设备machine值
hardware_model string 是 仅限iOS设备 设备model值
physical_memory_byte string 是 仅限iOS设备 物理内存
harddisk_size_byte string 是 仅限iOS设备 硬盘大小
system_update_sec string 是 仅限iOS设备 系统更新时间
time_zone string 是 仅限iOS设备 时区

*对安卓设备请求，imei、imei_md5、android_id、android_id_md5至少要填写其中一个；oaid或腾讯id获取工具提供的tickets，至少提供一种

名称 类型 必填 限制 说明
connect_type int32 是 可能取值:
0 - 未知
1 - wifi
2 - 2G
3 - 3G
4 - 4G		 联网方式。不填写将无广告返回；填未知，会严重影响流量变现效果。
carrier int32 是 可能取值:
0 - 未知
1 - 移动
2 - 联通
3 - 电信		 运营商。不填写将无广告返回；填未知，会影响流量变现效果。
ip string 是 仅限iOS设备 1.请从服务端获取IP，不要从客户端获取IP
2.优先上报IPV4地址，如果没有则上报IPV6地址
3.请上报公网IP，不要上报内网IP（例如192.168.0.100等）
4.如果X-Forward-For中包含多个公网IP，优先上报第一个公网IP
ua string 是 仅限iOS设备 客户端WebView的UserAgent信息
名称 类型 必填 限制 说明
lat int32 否 用户原始GPS坐标的纬度*1,000,000。该参数会用于基于地理位置的广告的定向，正确填写有助于提高流量变现效果。
lng int32 否 用户原始GPS坐标的经度*1,000,000。该参数会用于基于地理位置的广告的定向，正确填写有助于提高流量变现效果。
location_accuracy double 否 经纬度精度半径，单位为米。该参数会用于基于地理位置的广告的定向，正确填写有助于提高流量变现效果。
coord_time int64 否 获取经纬度(lat/lng)的时间。其值为从GMT 1970-01-01 00:00:00至今的毫秒值。

广告请求接口-请求示例

广告请求接口-响应数据

广告请求接口响应数据定义

响应的JSON数据包含三部分内容，分别是返回码ret、返回码描述msg和数据data，如下表所示。未在本文档中说明但出现在响应中的字段，是腾讯内部系统接口，随时可能变更，请勿使用。

名称 类型 必填 限制 说明
ret int64 是 返回码。非0表示请求失败，处理措施详见附录广告请求返回码列表。流量方必须首先检查该参数，在没有发生错误的情况下，再去解析广告数据data。
msg string 是 解释ret返回码含义
data object 是 广告数据，见data JSON对象
名称 类型 必填 限制 说明
{pos.id} object 是 名称是本次请求的广告位ID。参数值是该广告位的广告数据，见{pos.id} JSON对象
名称 类型 必填 限制 说明
list Array 是 非资质通荐广告位：该数组的每个元素对应一条广告的数据，返回广告个数不超过请求广告个数；
资质通荐广告位：数组的每个元素对应一条广告或资讯数据，可以通过元素中“type”字段识别当前元素为广告或者资讯；
数组元素（广告）定义见 list JSON数组元素（广告）
数组元素（资讯）定义见 list JSON数组元素（资讯）
名称 类型 必填 限制 说明
type string 否 仅资质通荐广告位返回，可能取值：
information – 资讯
ad – 广告		 list JSON数组元素类型：ad表示该对象为广告，解析时需要按照广告的对象格式解析；information表示该对象为资讯，解析时需要按照资讯内容解析。
ad_id string 是 广告ID
impression_link string 是 曝光上报链接
video_view_link string 否 仅视频广告返回 视频播放信息上报链接
click_link string 是 点击上报链接(需要宏替换，详见点击上报请求数据部分)
interact_type int32 是 可能取值：
0 - 打开网页
1 - app下载		 当广告被点击后，发生的交互行为类型。对不同交互类型的广告，处理方式有差异：
1. 可以根据该参数值进行不同方式的渲染
2. 该参数取值不同，点击上报返回数据的处理方式不同，详见点击上报响应数据部分
3.对app下载类型的广告还需要进行转化上报，详见转化上报部分
conversion_link string 否 仅当返回APP下载类广告（interact_type=1. 或当返回应用直达广告（customized_invoke_url参数存在）时，该参数有效 转化上报地址(需要宏替换，详见转化上报请求数据部分）
crt_type int32 否 可能取值：
2 – 图片（逐渐下线）
7 – 图文（1图2文或3等比例小图2文，逐渐下线）
11 – 图文（2图2文）
20 – 视频（1横版视频2图2文或1竖版视频2图2文）
24 - 图文（3等比例小图2文）		 素材类型。目前共有图片、图文和视频等3种类型。不同类型广告位支持的>素材类型有差别，同一素材类型在不同类型广告位上的物料也有差别，具体情况是：

1. 开屏广告有图片和图文两种，物料如下：
a. 2图片: 一张宽高比为640:960或640:1136的图片（img_url字段，640:1136图片仅支持ios系统，图片宽高比由请求字段pos.weight和pos.height决定）
b. 7图文: 一张宽高比为640:960或640:1136的图片(img_url字段，640:1136图片仅支持ios系统，图片宽高比由请求字段pos.weight和pos.height决定)，两段文字(title, description)
c. 11 图文：一张宽高比为1080:1920的图片(img_url字段，图片宽高比由请求字段pos.weight和pos.height决定)，一张icon小图(img2_url，开屏广告无需使用)，两段文字(title, description)

2. 原生广告和资质通荐广告有图文和视频两种，物料如下:
a. 7 图文：三张小图（img_list，创建广告位时选择多主图，宽高比均为228:150的三张图片），两段文字(title, description)
b. 11图文: 一张大图（img_url，创建广告位时选择尺寸)，一张icon小图(img2_url)，两段文字(title, description)
c. 20 横视频：一张大图（img_url，创建广告位时选择尺寸)，一张icon小图(img2_url)，两段文字(title, description) ，一条宽高比为1280:720的视频(video_url)
d. 20 竖视频：一张大图（img_url，创建广告位时选择尺寸)，一张icon小图(img2_url)，两段文字(title, description) ，一条宽高比为720:1280的视频(video_url)
e. 24图文：三张小图（img_list，创建广告位时选择多主图，宽高比均为228:150的三张图片），两段文字(title, description)

3. 激励视频广告位依据app横竖状态返回横版视频或者竖版视频；注意：当创建激励视频广告位时选择竖屏状态下能出横版视频时，请保证视频播放器能兼容处理横竖版视频的展现；物料如下：
a. 20横视频：一张1280:720的大图（img_url)，一张300：300的小图(img2_url)，两段文字(title, description) ，>一条宽高比为16:9的视频(video_url)
b. 20竖视频：一张720:1280的大图（img_url)，一张300：300的小图(img2_url)，两段文字(title, description) ，一条宽高比为9:16的视频(video_url)广告渲染样式可参考见附录广告渲染样式示例。
img_url string 否 广告的图片url
img2_url string 否 icon url
img_list Array 否 三图两文广告的三张小图url
img_width int32 否 广告图片宽
img_height int32 否 广告图片高
title string 否 广告标题
description string 否 广告描述
video_url string 否 视频url
video_width int32 否 视频宽度，单位像素
video_height int32 否 视频高度，单位像素
package_name string 否 安卓APP包名
app_id int64 否 ios应用id
video_duration int32 否 视频时长
video_file_size int32 否 视频文件大小，单位为KB
relation_target string 否 可能取值：
0 – 不限
1 – 定向未安装
2 – 定向已安装		 广告的应用安装定向类型
customized_invoke_url string 否 应用直达url
ecpm_level string 否 表示本条广告实时的eCMP价格层级标签，每个层级标签对应线下约定的eCPM价格范围，成功返回值为String类型数字或字母，类型为String，具体含义线下约定对齐
ecpm int32 否 申请API实时竞价权限后可调用，权限相关请咨询运营经理 单位“分”
获取本次请求优量汇的参竞价格
rtb_price int32 否 API流量不适用 单位“分”
仅针对RTB接入方式的实时竞价流量适用
win_notice_url string 否 申请API实时竞价权限后可调用，权限相关请咨询运营经理 竞胜上报链接(需要宏替换，详见竞胜上报请求数据部分)
loss_notice_url string 否 申请API实时竞价权限后可调用，权限相关请咨询运营经理 竞败上报链接(需要宏替换，详见竞败上报请求数据部分)
名称 类型 必填 限制 说明
type string 否 仅资质通荐广告位返回，可能取值：
information – 资讯
ad – 广告		 list JSON数组元素类型：ad表示该对象为广告，解析时需要按照广告的对象格式解析；information表示该对象为资讯，解析时需要按照资讯内容解析。
information_type string 是 可能取值：
article – 文章
video – 视频
from string 是 资讯来源
title string 是 资讯标题
images Array 是 资讯图片列表
is_big_pic int32 是 可能取值：
0 – 小图
1 - 大图
imp_url string 是 资讯曝光监测。当资讯在信息流中曝光时上报。
url string 是 资讯详情页点击地址
comment_count int32 否 评论数
play_count int32 否 视频资讯的播放次数
run_time int32 否 视频资讯的播放时长

广告请求接口-响应示例

HTTP/1.1 200 OK

{
    "ret":0,
    "msg":"",
    "data":{
        "8050018672826551":{
            "list":[
                {
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=bSVdor67lmXY5!eoxbZOOOOb_CQu1rpTvJWGM8AVi0E3iy!2VnzgHLzz_dIL6pq5Fi8LxPtJYIBFM2jYvVXbDGMGQrr63raQ_9tzhiFUUlAjs1Bg_LUzJYNcxaOA!5MG!MwjlLYc!2CUmeGx6oWfp!BidFhL1ZzybbRTGcbUT1LynM1imRxQGexJkjBDHquCv7szfLd_ThR0S1cAqtlAIQ&i=1&os=2&datatype=json",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=bSVdor67lmXY5!eoxbZOOOOb_CQu1rpTvJWGM8AVi0E3iy!2VnzgHLzz_dIL6pq5Fi8LxPtJYIBFM2jYvVXbDGMGQrr63raQ_9tzhiFUUlAjs1Bg_LUzJYNcxaOA!5MG!MwjlLYc!2CUmeGx6oWfp!BidFhL1ZzybbRTGcbUT1LynM1imRxQGexJkjBDHquCv7szfLd_ThR0S1cAqtlAIQ&jtype=0&i=1&os=2&asi=%7B%22mf%22%3A%22Xiaomi%22%7D&acttype=0&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D",
                    "interact_type":0,
                    "crt_type":11,
                    "title":"链家717，租房换新季！",
                    "description":"两室一厅两卫+大阳台，家用电器齐全，佣金每1000减200！",
                    "img_url":"http://pgdt.gtimg.cn/gdt/0/DAAPzYQAUAALQABZBZXLOKDKDSAgqS.jpg/0?ck=bb5fd85d2dfe45d89c73d52f6391905a",
                    "img2_url":"http://pgdt.gtimg.cn/gdt/0/DAAPzYQAEsAEsAAUBZXK6GCzdJLQFu.jpg/0?ck=9807f69989ad965535fae4448e63dbd0"
                },
                {
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=!mq3jem6jprY5!eoxbZOODQykDLHprRMH65OvFKKvnuxmHadHDFZmHxCVhJgx4qdXJfEF3BzMO7ycM5WNA6vqTBcYqdnce!KjHDlc7j9XMPkPH7zXU5N9rEmO6tBdDvcoy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuOgpnXINM0Gbap7qjZMAzQ2LWZpHEZeu_Ix0wRx3Df14w&i=1&os=2&datatype=json",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=!mq3jem6jprY5!eoxbZOODQykDLHprRMH65OvFKKvnuxmHadHDFZmHxCVhJgx4qdXJfEF3BzMO7ycM5WNA6vqTBcYqdnce!KjHDlc7j9XMPkPH7zXU5N9rEmO6tBdDvcoy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuOgpnXINM0Gbap7qjZMAzQ2LWZpHEZeu_Ix0wRx3Df14w&jtype=0&i=1&os=2&asi=%7B%22mf%22%3A%22Xiaomi%22%7D&acttype=1&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D",
                    "conversion_link":"http://t.gdt.qq.com/conv/alliance/api/conv?client=6&action_id=__ACTION_ID__&click_id=__CLICK_ID__&product_id=1106228530",
                    "interact_type":1,
                    "crt_type":11,
                    "title":"沙城传说",
                    "description":"经典传奇回归，开局一把木剑，打蜈蚣爆出屠龙刀，系统回收，过瘾",
                    "img_url":"http://pgdt.gtimg.cn/gdt/0/DAAEEh2AUAALQABQBZXZivCx-g1rXm.jpg/0?ck=5422e0280124288729a93a024896e7c5",
                    "img2_url":"http://pgdt.gtimg.cn/gdt/0/DAAEEh2AEsAEsAAXBZXZiXDY-kMKbV.jpg/0?ck=c6066c8bae5de0fad07ab0739852ea5f"
                }
            ]
        }
    }
}

HTTP/1.1 200 OK

{
    "ret":0,
    "msg":"",
    "data":{
        "7010946296282620":{
            "list":[
                {
                    "ad_id":"78064987",
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=0UK1EIN9ibAzpwc26RfjJ1hUXwGgvOOvZLGy5ow!97_x!pE55QuV6QyA_KDCDBfW!u51XavIXZIS9IrLQAFrLyw7YqQr9r3w2tpmmqFlSoQ3a8trEKpgF1SgJdP_XP8aSjKJxWNbnuqC4yl7lRBTkB9ATQDfLYSj0wn0LSMH246WBhka14_39Xlm!NaokVnYq!opvRtU02dV5utkxBPFAH1UrPg6Clv_sC6qfM9iD48&i=1&os=1&datatype=json&xp=3",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=0UK1EIN9ibAzpwc26RfjJ1hUXwGgvOOvZLGy5ow!97_x!pE55QuV6QyA_KDCDBfW!u51XavIXZIS9IrLQAFrLyw7YqQr9r3w2tpmmqFlSoQ3a8trEKpgF1SgJdP_XP8aSjKJxWNbnuqC4yl7lRBTkB9ATQDfLYSj0wn0LSMH246WBhka14_39Xlm!NaokVnYq!opvRtU02dV5utkxBPFAH1UrPg6Clv_sC6qfM9iD48&jtype=0&i=1&os=1&acttype=0&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D&xp=3",
                    "interact_type":0,
                    "crt_type":7,
                    "title":"翡翠原厂地直供，高性价比",
                    "description":"买翡翠的注意！这个APP源头直供，比实体店便宜一半",
                    "img_list":[
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAKBb0aNwCQwwHkGo.jpg/0?ck=6106dfc36bee5dd8dec60b6d60e2db43",
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAbBb0aNzBvw07kQd.jpg/0?ck=a31a8c84ca8eae23ba4e961d0b3f41d4",
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAdBb0aN2AqTuDmq3.jpg/0?ck=017d4621bee5af0afaacddda0135b72e"
],
                    "app_id":982906456
                }
            ]
        }
    }
}

具体情况请以线上返回为主

HTTP/1.1 200 OK

{
    "data":{
        "ret":0,
        "msg":"",
        "5070332035836651":{
            "ret":0,
            "msg":"",
            "list":[
                {
                    "comment_num":10,
                    "from":"FX168财经报社",
                    "images":[
                        "http://inews.gtimg.com/newsapp_ls/0/2916045577_580328/0"
                    ],
                    "information_type":"article",
                    "is_big_pic":1,
                    "post_time":1519346685,
                    "title":"石油币发行后 委内瑞拉又瞄准了“石油黄金币”",
                    "type":"information",
                    "url":"http://op.inews.qq.com/m/LCA2018022300494700?channel=news&refer=openapi_for_rcmguangdiantong&alg_version=1&reasonInfo=&seq_no=&article_pos=×tamp=&pos_article_end=8080932055237642&pos_ralated=1070335065234653&top_banner=7060139085436614&app_id=1106619022&information_info=9FytuYO0Oxedbvx4mLqaeWAyNpzCTNS9SqW6h57xTrmBtATX2RSOUw"
                },
                {
                    "ad_id":"45458121",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=xaBkxd74I307nfb4wnVLYt4AJA189PHgaVOLok5NepmtUQ58YlV2SqVZu26VxaHVT_r73AjSWJXh0VPA5YqraIqEeuIt2a28PdveaufietqWQ6PNxD0ciLPSA!oyR8Cs0cv9MUShY1lW5H5BvaJuhAF9!BjIT6baT4NYaSKhkSTbwMPuUBlsaOxJkjBDHquCfve1p4WtkhEZruG3QJrBEg&jtype=0&i=1&os=1&acttype=0&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D",
                    "crt_type":11,
                    "description":"开局随机投胎，兄弟竟穿越当上皇帝，在这叱咤风云！",
                    "img2_url":"http://pgdt.gtimg.cn/gdt/0/DAAOIXYAEsAEsAAxBaWaKUA7HO1lL1.jpg/0?ck=373c9cdcdf231be294da40264e6c1b0c",
                    "img_url":"http://pgdt.gtimg.cn/gdt/0/DAAOIXYAUAALQABjBacbAYB0r1_aGR.jpg/0?ck=6b6dde7dd6847e2ce2db20aee4336945",
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=xaBkxd74I307nfb4wnVLYt4AJA189PHgaVOLok5NepmtUQ58YlV2SqVZu26VxaHVT_r73AjSWJXh0VPA5YqraIqEeuIt2a28PdveaufietqWQ6PNxD0ciLPSA!oyR8Cs0cv9MUShY1lW5H5BvaJuhAF9!BjIT6baT4NYaSKhkSTbwMPuUBlsaOxJkjBDHquCfve1p4WtkhEZruG3QJrBEg&i=1&os=1&datatype=json",
                    "interact_type":0,
                    "title":"叫我万岁爷",
                    "type":"ad"
                },
                {
                    "comment_num":0,
                    "from":"腾讯证券",
                    "images":[
                        "http://inews.gtimg.com/newsapp_ls/0/2916837832_196130/0"
                    ],
                    "information_type":"article",
                    "is_big_pic":0,
                    "post_time":1519362785,
                    "title":"沪指冲高回落涨0.09% 雄安新区概念股大涨",
                    "type":"information",
                    "url":"http://op.inews.qq.com/m/STO2018022301286200?channel=news&refer=openapi_for_rcmguangdiantong&alg_version=1&reasonInfo=&seq_no=&article_pos=×tamp=&pos_article_end=8080932055237642&pos_ralated=1070335065234653&top_banner=7060139085436614&app_id=1106619022&information_info=9FytuYO0Oxedbvx4mLqaeWAyNpzCTNS9SqW6h57xTrmBtATX2RSOUw"
                }
            ]
        }
    }
}

广告请求接口- 响应处理流程

HTTP响应状态码为200并且响应数据中返回码ret=0时，表示请求广告成功。当HTTP响应状态码不是200时，联盟后台建议立即发起广告请求重试但最多只能重试一次；其他异常情况，不允许重试。具体处理流程如下：

广告请求接口响应处理流程

曝光上报

当广告展示给用户并且满足腾讯广告联盟曝光有效性标准时，开发者需要实时将本次曝光事件上报给联盟后台。曝光有效性标准如下：

获取到的广告尽力曝光，不允许刻意舍弃某种类型的广告。每条广告只能曝光一次。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价，从而降低流量变现效果：

曝光上报-请求地址

曝光上报URL直接使用广告请求响应数据中的impression_link字段，该字段已经包含了完整的请求地址和请求数据（已经过URL编码），禁止开发者做任何修改。

曝光上报-请求数据

使用impression_link字段，无需开发者填写。

曝光上报-请求示例

GET http://v.gdt.qq.com/gdt_stats.fcg?viewid=JcOh4K3LVtyM36FJYvAKAF_yL7FjDsqIvTv5Okb!OqmRVZVS8grRgfb8mE9jYoS3BM_S5FP!mBZFagqd3pitSIXFLugPNNM75APKz15fpCA7Nk4H9DL2Ahm1KyByHV8GH2Hze4h6XRewMVpuIwReDjNtbh_alplvlZaYU3BNpH6EwUQ6YS9AO4d80Y!HEso908m3ktLbFLe6wzKcjP!ZTEGfycQ1SVBsYoeco3kALE8Q2OLoI!jjzgUFAII8BY_TUXTHvNtw!0BFSBqfcPivGUYAGavN3CsGjlNHDLISkrq4M4nBfKMOdhWSjiBSChpFUgxTRRG8Y64&datatype=json HTTP/1.1
Host: v.gdt.qq.com

曝光上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

名称 类型 必填 限制 描述
ret int64 是 返回码，非0表示失败
msg string 是 返回码描述信息

曝光上报-响应示例

HTTP/1.1 200 OK

{
 "ret":0,
  "msg":""
}

曝光上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起转化上报重试但最多只能重试一次；其他异常情况，不允许重试。

曝光上报接口响应处理流程

视频播放信息上报

对于视频广告，开发者需要在视频播放结束时，上报视频播放信息。在一次广告播放事件中用户可能多次播放视频，每次视频播放结束时，都要上报一次播放信息。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价，从而降低流量变现效果：

视频播放信息上报-请求地址

视频播放信息上报URL需要开发者对广告请求响应数据中video_view_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

视频播放信息上报-请求数据

video_view_link中需要替换的宏：

名称 类型 必填 限制 说明
__VIDEO_TIME__ int32 是 视频总时长，单位为秒
__BEGIN_TIME__ int32 是 视频播放开始时间，单位为秒。如果视频从头开始播放，则为0。
__END_TIME__ int32 是 视频播放结束时间，单位为秒。如果视频播放到结尾，则等于视频总时长。
__PLAY_FIRST_FRAME__ int32 是 视频是否从第一帧开始播放。从第一帧开始播放，则为1；否则，为0。
__PLAY_LAST_FRAME__ int32 是 视频是否播放到最后一帧。播放到最后一帧，则为1；否则，为0。
__SCENE__ int32 是 视频播放场景。推荐场景如下：
1 - 在广告曝光区域播放；
2 - 全屏竖屏、只展示视频；
3 - 全屏竖屏、屏幕上方展示视频、下方展示广告推广目标网页（参考附录广告渲染样式示例，仅适用于交互类型是打开网页的广告，目标网页由点击上报返回数据中取得，详见点击上报响应数据部分）；
4 - 全屏横屏、只展示视频；
0 - 其它开发者自定义场景
__TYPE__ int32 是 播放类型。
1 - 第一次播放；
2 - 暂停后继续播放；
3 - 重新开始播放。
__BEHAVIOR__ int32 是 播放行为。
1 - 自动播放（推荐联网方式为wifi或4G时，设置视频自动播放）；
2 - 点击播放。
__STATUS__ int32 是 播放状态。
0 - 正常播放；
1 - 视频加载中；
2 - 播放错误。

视频播放信息上报-请求示例

GET http://vr.gdt.qq.com/gdt_stats.fcg?&datatype=json&viewid=3fOzNrVLMUCYOAUpt_U94oWRGcW_STX5fYS7sdOMs46chbddtzrkhTTd6kAvaNL5L6DoWzgO5VXF83EaF!O5MNk4vq!Un!q1uRjaYt6WQ5y_Fen1gKkVr6f4jp8u9bh1oy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuNYHu2KUFcRnQerHewVpZwDLWZpHEZeu_Jiadr1uWzZAA&video=%7b%22vt%22%3a%2215%22%2c%22bt%22%3a%220%22%2c%22et%22%3a%225%22%2c%22bf%22%3a%221%22%2c%22ef%22%3a%220%22%2c%22pp%22%3a%221%22%2c%22pa%22%3a%221%22%2c%22pb%22%3a%221%22%2c%22ps%22%3a%220%22%7d HTTP/1.1
Host: v.gdt.qq.com

视频播放信息上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

名称 类型 必填 限制 描述
ret int64 是 返回码，非0表示失败
msg string 是 返回码描述信息

视频播放信息上报-响应示例

HTTP/1.1 200 OK

{
  "ret":0,
  "msg":""
}

视频播放信息上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起视频播放信息上报重试但最多只能重试一次；其他异常情况，不允许重试。

视频播放信息上报接口响应处理流程

点击上报

当广告交互区域（对大部分广告，可以是整个广告所在区域；对某些广告，如视频广告，可以是一个局部区域，比如一个出现在视频下方的“查看详情”按钮，参考附录广告渲染样式示例视频广告渲染示例）被用户点击时，开发者需要实时将本次点击事件上报给联盟后台并尽力引导用户到达广告目标地址（广告推广商品的网页地址或APP下载地址）。对联盟后台点击上报接口的1次调用，即可实现点击事件上报，并从响应数据中获得广告目标地址。用户发生N次点击则进行N次点击上报，禁止用户点击一次，但进行多次点击上报。以下情况可能导致联盟后台对广告播放事件不计费或影响>对流量质量的评价，从而降低流量变现效果：

点击上报-请求地址

点击上报URL需要开发者对广告请求响应数据中click_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

点击上报-请求数据

开发者在广告点击时需要捕获用户点击坐标，该值将在联盟后台用来帮助提升用户点击率，从而提高开发者收入。坐标均指相对于实际广告位左上角的坐标，如下图所示，箭头方向为正坐标方向，坐标单位为像素。

点击坐标系

click_link中以下宏都要替换，如无法获取坐标时，请替换为-999。

宏名称类型必填限制描述
__REQ_WIDTH__int32是广告请求中的广告位宽（请求数据中参数pos.width，如果请求不填，则无需替换）
__REQ_HEIGHT__int32是广告请求中的广告位高（请求数据中参数pos.height，如果请求不填，则无需替换）
__WIDTH__int32是实际广告位的宽，单位为像素
__HEIGHT__int32是实际广告位的高，单位为像素
__DOWN_X__int32是请正确获取有效值并替换，如无法获取时，需替换为-999。当未替换为有效值时，流量收益会受到不同程度的影响：
1.替换为-999，影响流量收益。全部为-999请求将不返回广告
2.替换为无效值（非数字格式或取值异常），影响流量收益
3.未替换：请求将不返回广告		用户手指按下时的横坐标。
__DOWN_Y__int32是用户手指按下时的纵坐标。
__UP_X__int32是用户手指离开设备屏幕时的横坐标。
__UP_Y__int32是用户手指离开设备屏幕时的纵坐标。

点击上报-请求示例

GET http://c.gdt.qq.com/gdt_mclick.fcg?viewid=JcOh4K3LVtyM36FJYvAKAF_yL7FjDsqIvTv5Okb!OqmRVZVS8grRgfb8mE9jYoS3BM_S5FP!mBZFagqd3pitSIXFLugPNNM75APKz15fpCA7Nk4H9DL2Ahm1KyByHV8GH2Hze4h6XRewMVpuIwReDjNtbh_alplvlZaYU3BNpH6EwUQ6YS9AO4d80Y!HEso908m3ktLbFLe6wzKcjP!ZTEGfycQ1SVBsYoeco3kALE8Q2OLoI!jjzgUFAII8BY_TUXTHvNtw!0BFSBqfcPivGUYAGavN3CsGjlNHDLISkrq4M4nBfKMOdhWSjiBSChpFUgxTRRG8Y64&jtype=0&i=1&acttype=1&s=%7B%22req_width%22%3A%22250%22%2C%22req_height%22%3A%22100%22%2C%22width%22%3A%22300%22%2C%22height%22%3A%22120%22%2C%22down_x%22%3A%22100%22%2C%22down_y%22%3A%2250%22%2C%22up_x%22%3A%22100%22%2C%22up_y%22%3A%2250%22%7D HTTP/1.1
Host: c.gdt.qq.com

点击上报-响应数据

名称 类型 必填 限制 说明
ret int64 是 返回码，非0表示失败
data object 是 数据，包含APP下载地址。见data JSON对象
名称 类型 必填 限制 说明
dstlink string 是 APP的下载地址
clickid string 是 点击ID。需缓存下来，用于后续转化上报。

点击上报-响应示例

HTTP/1.1 302 Moved Temporarily
Location: http://zt.jd.com/ad/appjump.shtml?turl=http%3A%2F%2Fsale.jd.com%2Fm%2Fact%2FZhiH2XuDdcqoK.html&platform=2&qz_gdt=vwgbqwdsaaah7seyb62q

HTTP/1.1 200 OK

{
    "ret":0,
    "data":{
        "dstlink":"http://imtt.dd.qq.com/16891/335E360BFA5B5127F12E43BC480BE11A.apk?fsname=com.sohu.newsclient_5.7.2_112.apk&csr=4d5s&_gdt_ma_cdn_cb=1&qz_gdt=jarbawhga4akgqsrylma&appid=100898297",
        "clickid":"jarbawhga4akgqsrylma"
    }
}

点击上报-响应处理流程

当发生以下情况时，联盟后台建议立即发起点击上报重试但最多只能重试一次；其他异常情况，不允许重试。

点击上报接口响应处理流程

转化上报

转化上报-请求地址

转化上报URL需要开发者对广告请求响应数据中conversion_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

转化上报-请求数据

conversion_link中需要替换的宏：

宏名称 类型 必填 限制 描述
__ACTION_ID__ int32 是 可能取值：
5 - 下载开始
6 - 安装完成

7 - 下载完成
245 – 应用直达广告尝试唤起APP
246 – 应用直达广告唤起APP成功
247 – 应用已安装
248 – 应用未安装
249 – 无法获取应用安装信息		 转化行为类型
__CLICK_ID__ string 是 interact_type为0且customized_invoke_url存在时，替换为点击上报响应的重定向Location中"qz_gdt"参数的参数值；
interact_type为1时，替换为点击上报响应的"clickid"字段

转化上报- 请求示例

下载开始
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=5&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

下载完成
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=7&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

安装完成
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=6&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用直达广告尝试唤起APP
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=245&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用直达广告唤起APP成功
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=246&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用已安装
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=247&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用未安装
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=248&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

无法获取应用安装信息
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=249&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

转化上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

名称 类型 必填 限制 说明
ret int64 是 返回码，非0表示失败
msg string 是 返回码描述信息

转化上报-响应示例

HTTP/1.1 200 OK

{
  "ret":0,
  "msg":""
}

转化上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起转化上报重试但最多只能重试一次；其他异常情况，不允许重试。

转化上报接口响应处理流程

竞胜上报

竞胜上报-请求地址

竞胜上报URL需要开发者对广告请求响应数据中win_notice_url字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

竞胜上报-请求数据

win_notice_url中需要替换的宏：

宏名称 类型 必填 限制 描述
__ACTION_PRICE__ int32 是 单位“分”
要求使用RAS加密算法进行加密，之后进行base64编码，申请权限时需同时申请RAS加密公钥		 竞胜价格

竞胜上报-响应说明

开发者不必等待竞胜url的返回。正常情况下，HTTP响应状态码为200；其他异常情况，不允许重试。

竞败上报

竞败上报-请求地址

竞败上报URL需要开发者对广告请求响应数据中loss_notice_url字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

竞败上报-请求数据

loss_notice_url中需要替换的宏：

宏名称 类型 必填 限制 描述
__ACTION_PRICE__ int32 否 单位“分”
要求使用RAS加密算法进行加密，之后进行base64编码，申请权限时需同时申请RAS加密公钥		 竞胜方报价
__ACTION_LOSS__ int32 否 腾讯联盟失败原因
__ACTION_SEAT_ID__ int32 否 1 竞争力不足
2 竞价回包返回超时，上报接口待开放
3 竞价回包不合法（无广告填充且返回未参竞错误码），上报接口待开放
10001 其他		 竞胜方ID

竞败上报-响应说明

开发者不必等待竞败url的返回。正常情况下，HTTP响应状态码为200；其他异常情况，不允许重试。

测试联调

联调说明

测试联调的广告位ID

广告位类型 广告位ID app_id app_bundle_id os 可以出的广告类型
（crt_type + interact_type）
原生_1280:720 android 8050018672826551 1104241296 com.test.android android 与线上1280:720原生广告位配置相同
图文 + 随机interact_type
原生 _1200:627 android 6000525126331218 1104241296 com.test.android android 与线上1200:627原生广告位配置相同
图文 + 随机interact_type
原生 _800:1200 android 6040929166638239 1104241296 com.test.android android 与线上800:1200原生广告位配置相同
图文 + 随机interact_type
原生_视频_android 1020827859537176 1104241296 com.test.android android 只返回视频广告的广告位
原生_1280:720 ios 2080511602420459 1104238667 com.test.ios ios 与线上1280:720原生广告位配置相同
图文 + 随机interact_type
原生 _1200:627 ios 2030620166935226 1104238667 com.test.ios ios 与线上1200:627原生广告位配置相同
图文 + 随机interact_type
原生_800:1200 ios 5060320176531341 1104238667 com.test.ios ios 与线上800:1200原生广告位配置相同
图文 + 随机interact_type
原生_视频_ios 6000425899956957 1104238667 com.test.ios ios 只返回视频广告的广告位
开屏android 7070310684196198 1104241296 com.test.android android 与线上开屏广告位配置相同，广告的crt_type和interact_type随机
开屏ios 2080419644199129 1104238667 com.test.ios ios 与线上开屏广告位配置相同，广告的crt_type和interact_type随机
资质通荐android 3080023868837656 1104241296 com.test.android android 与线上1280:720原生广告位配置相同
图文 + 随机interact_type
资质通荐ios 5070332035836651 1104238667 com.test.ios ios 与线上1280:720原生广告位配置相同
图文 + 随机interact_type
激励视频_android（竖屏不可出横版广告） 8000045247127259 1104241296 com.test.android android 只返回视频广告的广告位
激励视频_ios（竖屏不可出横版广告） 9010049257121298 1104238667 com.test.ios ios 只返回视频广告的广告位
激励视频_android（竖屏可以出横版广告） 9050744247528300 1104241296 com.test.android android 只返回视频广告的广告位
激励视频_ios（竖屏可以出横版广告） 4030447202783113 1104238667 com.test.ios ios 只返回视频广告的广告位

附录

API基础数据类型定义

类型 含义
bool 布尔型
int32 32位有符号整数
int64 64位有符号整数
double 双精度浮点型
string 字符串
object JSON对象类型

开屏广告位宽和高填写逻辑及渲染建议

广告位类型 width:height 屏幕宽高
开屏 640:960或1080：1920或640:1136（只在ios系统上支持） 2:3
开屏 1080*1920或640:1136（只在ios系统上支持） 9:16

ios设备型号取值列表

系统返回原始值 取值 系统返回原始值 取值 系统返回原始值 取值
iPhone1,1 iPhone 1 iPad1,1 iPad iPod1,1 iPod Touch 1
iPhone1,2 iPhone 3G iPad2,1 iPad 2 iPad4,7 iPad Mini 3
iPhone2,1 iPhone 3GS iPad2,2 iPad 2 iPad4,8 iPadMini 3
iPhone3,1 iPhone 4 iPad2,3 iPad 2 iPad4,9 iPad Mini 3
iPhone3,2 iPhone 4 iPad2,4 iPad 2 iPad5,1 iPad Mini 4
iPhone3,3 iPhone 4 iPad3,1 iPad 3 iPad5,2 iPad Mini 4
iPhone4,1 iPhone 4S iPad3,2 iPad 3 iPad5,3 iPad Air 2
iPhone5,1 iPhone 5 iPad3,3 iPad 3 iPad5,4 iPad Air 2
iPhone5,2 iPhone 5 iPad3,4 iPad 4 iPod2,1 iPod Touch 2
iPhone5,3 iPhone 5c iPad3,5 iPad 4 iPod3,1 iPod Touch 3
iPhone5,4 iPhone 5c iPad3,6 iPad 4 iPod4,1 iPod Touch 4
iPhone6,1 iPhone 5s iPad2,5 iPad Mini iPod5,1 iPod Touch 5
iPhone6,2 iPhone 5s iPad2,6 iPad Mini iPod6,1 iPod Touch 6
iPhone7,1 iPhone 6 Plus iPad2,7 iPad Mini i386 32-bit Simulator
iPhone7,2 iPhone 6 iPad4,1 iPad Air x86_64 64-bit Simulator
iPhone8,1 iPhone 6s iPad4,2 iPad Air
iPhone8,2 iPhone 6s Plus iPad4,3 iPad Air
iPhone8,4 iPhone SE iPad4,4 iPad Mini 2
iPhone9,3 iPhone 7 iPad4,5 iPad Mini 2
iPhone9,4 iPhone 7 Plus iPad4,6 iPad Mini 2

资质通荐垂直频道列表

垂直频道ID 含义
98 推荐
100 时事
103 军事
104 财经
105 汽车
106 体育
107 娱乐
108 房产
109 科技
110 教育
111 时尚
112 文化
113 摄影
115 旅游
116 健康
117 星座命理
118 美食
119 家居
122 育儿
123 科普
128 动漫
136 图片
143 生活
1002 社会
10001 国际
20001 视频

资质通荐地域频道列表

地域频道ID 含义
91101 北京
91201 天津
91302 唐山
91306 保定
91304 邯郸
92101 沈阳
92102 大连
93201 南京
93202 无锡
93205 苏州
93101 上海
93301 杭州
93302 宁波
93303 温州
93307 金华
93501 福州
94101 郑州
94201 武汉
94401 广州
94403 深圳
94406 佛山
94413 惠州
94419 东莞
94420 中山
95001 重庆
95101 成都

广告请求返回码列表

当无广告返回时，对照错误码，首先检查填写逻辑，常见问题如下：

具体返回错误码含义说明可点击连接查询

广告渲染样式示例

原生和开屏广告渲染示例



视频广告播放示例



三小图广告渲染示例



资讯列表页广告示例



资讯文章页广告示例

应用直达广告处理逻辑要求

权限申请

应用直达广告是一种特殊形式的广告形式。需要开发者具有一定的处理能力才能确保直达率满足平台的要求。因此，此类广告只针对部分开发者开放权限，并需要配合完成审核验证，才能准许播放。具体的申请方式，可与联盟对接运营接口人联系获取。

请求处理

在请求环节，pos JSON对象中的deep_link_version字段需要为必填，只有必填的情况下才可能请求到应用直达广告。
在响应环节， list JSON数组元素（广告）中的3个字段需要处理：

应用广告过滤处理

应用直达类广告为保证直达率，广告主往往会选择已安装或未安装定向，那么开发者需要结合这个定向情况以及app广告的包名，来检测用户当时手机上是否安装了此款app，如果符合预期则展示广告，否则需要将广告过滤，如果原生样式有多条广告请求则展示下一条广告，其他样式则重新发起请求。重新发
起请求时建议使用last_ad_ids接口，过滤掉上次拉取的广告，避免再次请求拉到相同的广告。

示例：

点击处理

在响应环节， list JSON数组元素（广告）中的customized_invoke_url 是应用直达的url。当用户发生点击时，需要正常进行点击的上报。但是拿到响应后的处理逻辑与普通广告不同。
开发者需要在点击上报后，直接处理customized_invoke_url。当唤起目标app成功时，正常。当唤起目标app失败时，则使用点击响应data JSON对象的dstlink进行跳转。

转化处理

应用直达类广告存在唤起目标app成功及失败2种情况。需要使用点击响应中的data JSON对象的clickid进行上报：

上报正常的情况下，尝试上报的次数-唤起成功的次数=唤起失败的次数。

测试联调

测试联调时，针对开通了应用直达类广告权限的开发者，除了常规的测试联调外，需要额外进行上文中广告过滤处理、点击处理和转化处理中要求的测试

Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇