腾讯联盟 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 | 孟嵩、陈雪雅、周敏菲 | 支持时区等字段 |
关于文档
对有APP流量变现需求但由于各种原因无法嵌入腾讯广告联盟SDK的开发者,腾讯广告联盟提供基于广告播放API的合作方式。开发者应保证获得用户授权同意,由开发者收集并向腾讯提供如下字段。本文档详细介绍了广告播放API的商务对接流程和接口协议等内容。
背景知识
名词解释
开发者:指腾讯广告联盟官网(以下简称联盟平台)的注册会员。用QQ号注册成功后系统会自动生成一个新的固定为12位数字的账号ID,这个ID是腾讯广告联盟识别开发者的唯一ID。
媒体:指在联盟平台创建的媒体,这里媒体等价于应用的概念。创建媒体时获得的ID将成为应用ID,这个ID是腾讯广告联盟识别您应用的唯一ID。
广告位:指在联盟平台为媒体创建的某种类型(开屏、原生、资质通荐、激励视频,从3.3版本开始,联盟api将不支持banner和插屏样式,需要继续使用该样式的开发者建议使用原生广告进行渲染或转接SDK)的广告位置。创建广告位时获得的ID将成为广告位ID,这个ID是腾讯广告联盟识别您广告位置的唯一ID。
资质通荐广告:也称信息流资讯广告,是腾讯广告联盟推出的一种新的广告产品。此产品是由腾讯系的优质资讯内容和广告组合而成,并打通了资讯内容算法和广告算法,最终以“信息流”的形式输出给开发者的优质资讯和广告的推荐组合。
技术规范
有关标准HTTP协议,可参考 RFC2616 或 维基百科-HTTP 。有关URL编码,可参考RFC3986或维基百科-Percent-encoding。有关JSON数据格式,可参考 JSON.ORG 或 维基百科–JSON 。
对接流程
流程介绍

前期准备:API合作以腾讯广告联盟商务人员(以下简称商务人员)邀请的方式发出,开发者在接受邀请后,需在商务人员指导下填写《API接入申请表》。
- 1.注册开户:审核通过后,开发者需先在联盟平台注册成为会员,在审核过程中,即可联系商务人员获取《腾讯广告联盟广告播放API说明文档》。
- 2.开发联调:开发者根据文档要求进行功能开发,开发完成后,先使用测试广告位进行联调。在此过程中如果有疑问,请联系商务人员。
- 3.审核验证:联调成功后,开发者将预发布的APK包和开发者ID提供给商务人员进行验证广告样式,验证通过后,开通API权限。
- 4.灰度放量:获得权限后,在联盟平台创建API接入的媒体和广告位,将广告请求中的测试广告位ID替换成新创建的,开始进行灰度放量。在灰度过程中,联盟运营人员会进行效果验证,验证通过,开始正式放量。验证未通过,需开发者根据优化建议做调整修改,完成后进行二次验证,仍未通过,将收回API权限推荐使用SDK合作。
- 5.正式上线:灰度验证后,开始正式上线放量,开发者可以登录联盟平台查看流量收益情况。
注意事项
- 1.新流量请求限制:为更好地了解您的流量、匹配更合适的广告,在新创建广告位流量上线初期,腾讯广告联盟会进行广告日请求量限制。当达到日请求量上限时,将无广告返回,且会有返回码提示,具体处理方式请参考附录广告请求返回码列表。
- 2.原生广告/激励视频广告接入提示:在联盟平台创建广告位时,默认不能创建原生/激励视频广告位,如果开发者要接入原生/激励视频广告,需要联系商务人员沟通申请。
广告播放API
腾讯广告联盟后台服务(以下简称联盟后台)通过广告播放API对外提供广告请求和数据上报服务。该API包含如下四个接口,调用流程见下文广告播放时序图。
1.广告请求:腾讯广告联盟支持两种方式请求广告。
a.开发者APP通过后台服务向联盟后台请求广告
b.开发者APP直接向联盟后台请求广告
强烈建议开发者通过后台服务请求广告。如果是想让APP直接请求广告,首选SDK接入方式,开发工作量小而且流量变现效果通常会更好。联盟后台后续可能会禁止APP直接发起广告请求。
2.曝光上报:APP将广告展示给用户后,APP必须实时、直接向联盟后台上报曝光,不允许通过开发者后台服务上报。
3.点击上报:用户点击广告后,APP必须实时、直接向联盟后台上报点击,不允许通过开发者后台服务上报。
4.转化上报:目前只对app下载类广告有意义,特指下载开始、下载完成、安装完成这3种转化行为的上报。转化行为发生后,APP必须实时、直接向联盟后台上报,不允许通过后台服务上报。
通信方式
联盟后台与外部调用方的基础通信协议采用HTTP协议和HTTPS协议。
超时时间
不考虑网络链路(调用方与联盟后台服务器之间的传输链路)时延,对99%的请求,联盟后台能在200ms内响应(资质通荐广告在400ms内响应)。广告请求超时时间建议设置1秒;其他接口建议设置较大的超时时间,比如10秒。
编码方式
若无特殊说明,所有输入参数、返回结果的字节编码均使用UTF-8(无BOM头)。
HTTP请求
HTTP Method
使用GET方法HTTP Header
如果是由后台服务发起广告请求,则需要在HTTP请求头部填充如下字段;其它情况下无特殊请求头部字段要求。
名称 | 必填 | 说明 |
---|---|---|
X-Forwarded-For | 是 | 用户设备的公网出口IPv4地址。点分字符串形式,示例:14.17.22.37。当广告请求由server发起时,该字段务必正确填写,否则将严重影响流量变现效果。 |
User-Agent | 否 | 用户设备HTTP请求头中的User-Agent字段。 |
Referer | 否 | 用户设备HTTP请求头中的Referer字段。 |
- HTTP 请求数据
请求数据放在URL查询字符串中,使用键值对形式(例如url格式为http://domain/path?name1=value1&name2=value2 ,其中“?”之后的部分是查询字符串)。查询字符串中每个参数的值(value1和value2)必须进行URL编码。
HTTP响应
HTTP状态码
不同接口在不同情况下会返回不同的HTTP状态码,在下文详细介绍每个接口时说明。HTTP Header
无响应头部字段要求。HTTP响应数据
响应数据(HTTP Response Body)如果不为空,均使用JSON格式
广告请求接口
开屏广告位必须实时请求广告(实时是指在广告位即将展示给用户或已经展示给用户时),不允许缓存广告;其他广告位可以预请求广告并缓存起来,然后在合适的时机将广告曝光。预请求广告可能产生广告预算不足等一系列问题,从而影响流量变现效果,建议所有类型广告位实时请求广告。
广告请求接口-请求地址
非资质通荐广告位(开屏、原生、激励视频):
资质通荐广告位:
广告请求接口-请求数据

可选参数填写原则: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对象。 |
- pos 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 | 否 | 视频广告最大播放时长,单位为秒。 |
- media JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
app_id | string | 是 | 在联盟平台创建媒体时分配的应用ID。不填写或填写错误将不返回广告。 | |
app_bundle_id | string | 是 | 可能取值: 1. android设备:使用package name 2. ios设备:使用bundle id |
应用包名。不填写或填写错误将不返回广告。请求填写包名要与注册媒体时填写保持一致,不一致将无广告返回。 |
- device JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
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,至少提供一种
- network JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
connect_type | int32 | 是 | 可能取值: 0 - 未知 1 - wifi 2 - 2G 3 - 3G 4 - 4G |
联网方式。不填写将无广告返回;填未知,会严重影响流量变现效果。 |
carrier | int32 | 是 | 可能取值: 0 - 未知 1 - 移动 2 - 联通 3 - 电信 |
运营商。不填写将无广告返回;填未知,会影响流量变现效果。 |
- geo JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
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至今的毫秒值。 |
广告请求接口-请求示例
- android设备原生广告位请求
GET http://mi.gdt.qq.com/api/v3?api_version=3.0&pos=%7B%22id%22%3A 8050018672826551%2C%22ad_count%22%3A2%7D&media=%7B%22app_id%22%3A%221104241296%22%2C%22app_bundle_id%22%3A%22com.test.android%22%7D&device=%7B%22os%22%3A%22android%22%2C%22os_version%22%3A%226.0.1%22%2C%22model%22%3A%22MI%204LTE%22%2C%22manufacturer%22%3A%22Xiaomi%22%2C%22device_type%22%3A1%2C%22screen_width%22%3A360%2C%22screen_height%22%3A640%2C%22orientation%22%3A0%2C%22imei%22%3A%22123456789009876%22%2C%22android_id%22%3A%229774d56d682e549c%22%2C%22android_ad_id%22%3A%22d725f723-86ea-466a-883d-5be2ca568241%22%7D&network=%7B%22connect_type%22%3A1%2C%22carrier%22%3A3%7D&geo=%7B%22lat%22%3A39925625%2C%22lng%22%3A116333285%2C%22coord_time%22%3A1473416991123%7D HTTP/1.1 Host: mi.gdt.qq.com X-Forwarded-For: 14.17.22.35 User-Agent: Mozilla/5.0 (Linux; U; Android 4.4.4; zh-cn; MI 4LTE Build/KTU84P) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.8 Mobile Safari/537.36 Referer: http://www.qq.com
android设备资质通荐广告位请求
GET http://info.gdt.qq.com/information/api/v3?api_version=3.0.0&pos=%7b%22id%22%3a3080023868837656%2c%22ad_count%22%3a1%2c%22channel%22%3a98%2c%22page_number%22%3a2%7d&media=%7b%22app_id%22%3a%221104241296%22%2c%22app_bundle_id%22%3a%22com.test.android%22%7d&device=%7b%22os%22%3a%22android%22%2c%22os_version%22%3a%226.0.1%22%2c%22model%22%3a%22MI+4LTE%22%2c%22manufacturer%22%3a%22Xiaomi%22%2c%22device_type%22%3a1%2c%22screen_width%22%3a360%2c%22screen_height%22%3a640%2c%22dpi%22%3a480%2c%22orientation%22%3a0%2c%22imei%22%3a%22123456789009876%22%2c%22android_id%22%3a%229774d56d682e549c%22%2c%22android_ad_id%22%3a%22d725f723-86ea-466a-883d-5be2ca568241%22%7d&network=%7b%22connect_type%22%3a1%2c%22carrier%22%3a3%7d&geo=%7b%22lat%22%3a39925625%2c%22lng%22%3a116333285%2c%22coord_time%22%3a1473416991123%7d HTTP/1.1 Host: info.gdt.qq.com X-Forwarded-For: 14.17.22.35 User-Agent: Mozilla/5.0 (Linux; U; Android 4.4.4; zh-cn; MI 4LTE Build/KTU84P) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.8 Mobile Safari/537.36 Referer: http://www.qq.com
ios设备激励视频广告位请求(横屏状态)
GET http://mi.gdt.qq.com/api/v3?api_version=3.0&pos={%22id%22:7010037942894023,%22ad_count%22:1}&media={%22app_id%22:%221104238667%22,%22app_bundle_id%22:%22com.test.ios%22}&device={%22os%22:%22ios%22,%22os_version%22:%2210.1.1%22,%22model%22:%22iPhone%205s%22,%22device_type%22:1,%22orientation%22:90,%22idfa%22:%22008A39D4-CF91-40F8-ADF0-E119F206AE6E%22}&network={%22connect_type%22:1,%22carrier%22:3}&geo={%22lat%22:39925625,%22lng%22:116333285,%22coord_time%22:1473416991123} HTTP/1.1 Host: mi.gdt.qq.com X-Forwarded-For: 14.17.22.35 User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12F70 Safari/600.1.4 Referer: http://www.qq.com
ios资质通荐广告位请求
GET http://info.gdt.qq.com/information/api/v3?api_version=3.0.0&pos=%7B%22id%22%3A5070332035836651%2C%22channel%22%3A98%7D&media=%7B%22app_id%22%3A%221104238667%22%2C%22app_bundle_id%22%3A%22com.test.ios%22%7D&device=%7B%22os%22%3A%22ios%22%2C%22os_version%22%3A%2210.1.1%22%2C%22model%22%3A%22iPhone%205s%22%2C%22device_type%22%3A1%2C%22dpi%22%3A320%2C%22orientation%22%3A90%2C%22idfa%22%3A%22008A39D4-CF91-40F8-ADF0-E119F206AE6E%22%7D&network=%7B%22connect_type%22%3A1%2C%22carrier%22%3A3%7D&geo=%7B%22lat%22%3A39925625%2C%22lng%22%3A116333285%2C%22coord_time%22%3A1473416991123%7D HTTP/1.1 Host: info.gdt.qq.com X-Forwarded-For: 14.17.22.35 User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12F70 Safari/600.1.4 Referer: http://www.qq.com
广告请求接口-响应数据

响应的JSON数据包含三部分内容,分别是返回码ret、返回码描述msg和数据data,如下表所示。未在本文档中说明但出现在响应中的字段,是腾讯内部系统接口,随时可能变更,请勿使用。
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
ret | int64 | 是 | 返回码。非0表示请求失败,处理措施详见附录广告请求返回码列表。流量方必须首先检查该参数,在没有发生错误的情况下,再去解析广告数据data。 | |
msg | string | 是 | 解释ret返回码含义 | |
data | object | 是 | 广告数据,见data JSON对象 |
- data JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
{pos.id} | object | 是 | 名称是本次请求的广告位ID。参数值是该广告位的广告数据,见{pos.id} JSON对象 |
- {pos.id} JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
list | Array | 是 | 非资质通荐广告位:该数组的每个元素对应一条广告的数据,返回广告个数不超过请求广告个数; 资质通荐广告位:数组的每个元素对应一条广告或资讯数据,可以通过元素中“type”字段识别当前元素为广告或者资讯; 数组元素(广告)定义见 list JSON数组元素(广告) 数组元素(资讯)定义见 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,具体含义线下约定对齐 |
- list JSON数组元素(资讯)
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
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时,联盟后台建议立即发起广告请求重试但最多只能重试一次;其他异常情况,不允许重试。具体处理流程如下:

曝光上报
当广告展示给用户并且满足腾讯广告联盟曝光有效性标准时,开发者需要实时将本次曝光事件上报给联盟后台。曝光有效性标准如下:
- 广告展示区域的50%以上像素点在用户屏幕上并且持续可见时间超过1秒钟。
获取到的广告尽力曝光,不允许刻意舍弃某种类型的广告。每条广告只能曝光一次。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价,从而降低流量变现效果:
- 1.对一次广告播放事件,没有曝光上报
- 2.对一次广告播放事件,重复曝光上报
- 3.对一次广告播放事件,曝光上报与广告请求时间间隔太大
- 4.广告曝光率(曝光数/返回广告数)显著偏离正常水平
曝光上报-请求地址
曝光上报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时,联盟后台建议立即发起转化上报重试但最多只能重试一次;其他异常情况,不允许重试。

视频播放信息上报
对于视频广告,开发者需要在视频播放结束时,上报视频播放信息。在一次广告播放事件中用户可能多次播放视频,每次视频播放结束时,都要上报一次播放信息。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价,从而降低流量变现效果:
- 1.对一次广告播放事件,上报了错误的视频播放信息
- 2.对一次广告播放事件,视频播放信息上报与广告请求时间间隔太大
- 3.视频播放率(视频播放数/曝光数)显著偏离正常水平
视频播放信息上报-请求地址
视频播放信息上报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次点击上报,禁止用户点击一次,但进行多次点击上报。以下情况可能导致联盟后台对广告播放事件不计费或影响>对流量质量的评价,从而降低流量变现效果:
- 1.对一次广告播放事件,用户点击了广告但没有点击上报
- 2.对一次广告播放事件,点击上报与广告请求时间间隔太大
- 3.广告点击率(点击数/曝光数)显著偏离正常水平
点击上报-请求地址
点击上报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
点击上报-响应数据
- 1.对不同交互类型的广告,点击上报接口返回的数据不同:对于交互类型是打开网页的广告(广告请求响应interact_type=0),目标地址是网页,点击上报接口返回HTTP 302跳转,开发者在应用内或外部浏览器中展示网页。目前ios设备上的所有广告和安卓设备上部分广告是打开网页类型的广告(推广ios APP的广告跳转到Apple App Store的APP详情页地址)。从保护用户体验和广告转化效果角度考虑,建议安卓设备使用webview或内置浏览器打开,ios设备使用webview或SafariViewController打开。
注意:有些网页在打开后,会尝试唤起广告主APP以引导用户发生转化行为。强烈建议开发者使用的浏览器或webview支持唤起外部APP(ios设备上Safari浏览器和系统webview、SafariViewController已支持;安卓上浏览器和webview支持情况差异较大)。广告转化效果会影响腾讯广告联盟对流量质量的评
价,从而影响流量变现效果。 - 2.对于交互类型是APP下载的广告(广告请求响应interact_type=1),目标地址是APP下载地址,点击上报接口返回响应数据,开发者需要解析数据来获取APP下载地址,以及进行后续的转化数据上报。目前APP下载类广告只出现在安卓设备上。从保护用户体验和广告转化效果角度考虑,建议:非wifi环境
下弹出下载确认框,在用户确认后再发起下载;wifi环境下则直接下载。响应数据是JSON格式,包含两部分内容:返回码ret和数据data,如下表所示:
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
ret | int64 | 是 | 返回码,非0表示失败 | |
data | object | 是 | 数据,包含APP下载地址。见data JSON对象 |
- data JSON对象
名称 | 类型 | 必填 | 限制 | 说明 |
---|---|---|---|---|
dstlink | string | 是 | APP的下载地址 | |
clickid | string | 是 | 点击ID。需缓存下来,用于后续转化上报。 |
点击上报-响应示例
- 交互类型是打开网页(广告请求响应interact_type=0)
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
- 交互类型是APP下载(广告请求响应interact_type=1)
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"
}
}
点击上报-响应处理流程
当发生以下情况时,联盟后台建议立即发起点击上报重试但最多只能重试一次;其他异常情况,不允许重试。
- 1.广告是APP下载类广告并且HTTP响应状态码不是200
- 2.广告是打开网页类广告并且HTTP响应状态码不是302

转化上报
- 对于APP下载类型广告(广告请求响应字段interact_type=1),腾讯广告联盟需要追踪下载效果,包括下载开始率、下载完成率和安装率,所以需要APP上报下载开始、下载完成和安装完成。
- 对于应用直达类型广告(广告请求响应字段customized_invoke_url存在时),腾讯广告联盟需要追踪应用直达效果,包括尝试唤起APP率和唤起APP成功率,所以需要APP上报应用直达广告尝试唤起APP和应用直达广告唤起APP成功。对于APP场景下的应用直达类型广告(广告请求响应字段interact_type=1且customized_invoke_url存在时),腾讯广告联盟还需要追踪APP应用安装率(应用已安装/应用未安装/无法获取应用安装信息),所以还需要APP上报应用已安装/应用未安装/无法获取应用安装信息。
- APP及时准确地上报这些转化行为,会正面影响腾讯广告联盟对流量质量的评价,从而提高流量变现效果;反之,如果不上报或虚假上报,会负面影响腾讯广告联盟对流量质量的评价,从而降低流量变现效果。
转化上报-请求地址
转化上报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时,联盟后台建议立即发起转化上报重试但最多只能重试一次;其他异常情况,不允许重试。

测试联调
联调说明
- 1.非资质通荐广告位开发者从广告请求联调地址test.mi.gdt.qq.com/api/v3拉取广告,资质通荐广告位开发者从广告请求联调地址test.info.gdt.qq.com/api/v3拉取广告。
- 2.开发者需要遍历测试“测试联调的广告位ID”中相应广告位类型下列出的所有广告位,对每个广告位:
- a.测试每个广告请求参数的所有取值情况
- b测试对各种类型的广告的渲染情况
- c.测试对各种类型的广告的曝光上报、点击上报和转化上报情况
- 3.若测试时无法请求到APP下载类广告,可以将请求connect_type参数的值设成1(wifi)。但在线上环境务必根据真实联网方式填写connect_type参数。
- 4.注意:测试联调环境有QPS和日请求总量限制,请合理使用。
测试联调的广告位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对象类型 |
开屏广告位宽和高填写逻辑及渲染建议
- 1.开屏广告位width和height的可能取值见下表。具体填写逻辑,建议根据用户屏幕实际宽高进行选择,对于大尺寸的广告位宽和高,返回的图片会更清晰,图片文件体积一般也会更大。
- 2.渲染建议:由于手机屏幕尺寸比例众多,为保证渲染效果,建议对开屏渲染采用如下方法;
拿到素材后,以屏幕最上方中间为对齐基准,等比例缩放素材至宽度和屏幕宽度相同,并全屏铺开展示,铺开后,如果:- 1.素材高度大于屏幕高度时,裁剪广告素材底部,使素材宽高和屏幕宽高一致
- 2.素材高度小于屏幕高度时,则将素材等比缩放至高度和屏幕高度相同,对称裁剪素材两侧,使素材宽高和屏幕宽高一致
广告位类型 | 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 | 成都 |
广告请求返回码列表
当无广告返回时,对照错误码,首先检查填写逻辑,常见问题如下:
- 1.必填参数未填写
- 2.参数数据类型不正确
- 3.参数取值不合法。
具体返回错误码含义说明可点击连接查询
广告渲染样式示例





应用直达广告处理逻辑要求
权限申请
应用直达广告是一种特殊形式的广告形式。需要开发者具有一定的处理能力才能确保直达率满足平台的要求。因此,此类广告只针对部分开发者开放权限,并需要配合完成审核验证,才能准许播放。具体的申请方式,可与联盟对接商务接口人联系获取。
请求处理
在请求环节,pos JSON对象中的deep_link_version字段需要为必填,只有必填的情况下才可能请求到应用直达广告。
在响应环节, list JSON数组元素(广告)中的3个字段需要处理:
- customized_invoke_url:应用直达的url
- package name:安卓情况下app广告的包名。
- relation_target:app广告安装定向情况,让开发者知道这是否是一条广告主要求的安装定向广告。
应用广告过滤处理
应用直达类广告为保证直达率,广告主往往会选择已安装或未安装定向,那么开发者需要结合这个定向情况以及app广告的包名,来检测用户当时手机上是否安装了此款app,如果符合预期则展示广告,否则需要将广告过滤,如果原生样式有多条广告请求则展示下一条广告,其他样式则重新发起请求。重新发
起请求时建议使用last_ad_ids接口,过滤掉上次拉取的广告,避免再次请求拉到相同的广告。
示例:
- 当relation_target取值为1时,说明广告主定向的是未安装广告app的用户,此时开发者检测如果用户安装了“package name”的应用,则过滤掉广告,展示下一条返回的广告(原生样式)或重新发起请求(其他样式)。如果确实手机上没有安装“package name”的应用,则可以正常曝光。
- 当relation_target取值为2时,说明广告主定向的是已安装广告app的用户,此时开发者检测如果用户安装了“package name”的应用,则可以正常曝光。如果确实手机上没有安装“package name”的应用, 则过滤掉广告,展示下一条返回的广告(原生样式)或重新发起请求(其他样式)。
- 当relation_target取值为0时,不用做任何处理。
点击处理
在响应环节, list JSON数组元素(广告)中的customized_invoke_url 是应用直达的url。当用户发生点击时,需要正常进行点击的上报。但是拿到响应后的处理逻辑与普通广告不同。
开发者需要在点击上报后,直接处理customized_invoke_url。当唤起目标app成功时,正常。当唤起目标app失败时,则使用点击响应data JSON对象的dstlink进行跳转。
转化处理
应用直达类广告存在唤起目标app成功及失败2种情况。需要使用点击响应中的data JSON对象的clickid进行上报:
- 当尝试唤起目标app时,进行一次尝试上报:conversion_link的__ACTION_ID__宏替换为245。
- 当唤起目标app成功时,进行一次成功上报:conversion_link的__ACTION_ID__宏替换为246。
上报正常的情况下,尝试上报的次数-唤起成功的次数=唤起失败的次数。
测试联调
测试联调时,针对开通了应用直达类广告权限的开发者,除了常规的测试联调外,需要额外进行上文中广告过滤处理、点击处理和转化处理中要求的测试