Bidding 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增加竞胜竞败上报支持
v3.10 2022-04-18 赵正阳、左源 1.更新请求参数、响应字段说明
2.支持厂商应用商店下载类广告
3.新增广告点击交互处理流程
v3.11 2022-05-24 赵正阳、左源 支持微信小程序/小游戏广告
v3.12 2022-06-06 赵正阳、左源 支持Universal Link
v3.13 2022-06-24 左源、孟嵩 完善点击上报的具体逻辑说明,新增点击坐标获取代码示例

关于文档

对有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内响应。广告请求超时时间建议设置1秒;其他接口建议设置较大的超时时间,比如10秒。

编码方式

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

HTTP请求

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

HTTP响应

广告请求接口

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

广告请求接口-请求地址

http://mi.gdt.qq.com/api/v3

广告请求接口-请求数据

请求数据定义

可选参数填写原则: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地址。
support_app_store int32 可能取值:
1 – 请求厂商应用商店下载类广告。
是否请求厂商应用商店下载类广告。当该字段填1时,联盟后台可能返回厂商应用商店下载类广告,回包字段见market_url。
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列表。 最近曝光过的广告。联盟后台会过滤掉这些广告,不填写或填写错误可能导致短时间内多次请求返回的广告重复。
deep_link_version int32 可能取值:
1 - 请求应用直达广告。
是否请求应用直达广告。当该字段填1且该媒体已开通应用直达权限时,联盟后台可能返回应用直达广告,回包字段见customized_invoke_url;
其它情况下(该字段未填或填其他值或未开通应用直达权限),联盟后台只返回非应用直达广告。
max_duration int32 视频广告最大播放时长,单位为秒。
名称 类型 必填 限制 说明
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横竖屏。
激励视频广告位该参数为必填。
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/
idfa string 36个字符,仅限ios设备 ios设备的idfa,保留原始值。不填将不返回广告,填写错误会严重影响流量变现效果。
idfa_md5 string 32个字符,仅限ios设备 ios设备的idfa(如果出现字母,转为大写),取md5sum摘要,摘要小写,32位。该参数用来替补idfa,两者传其一即可,强烈建议优先填写idfa。
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设备 时区
wx_api_ver int64 仅限Android设备 微信内部SDK版本,详见附录微信小程序/小游戏广告处理逻辑
wx_installed bool 仅限iOS设备 是否已安装微信,详见附录微信小程序/小游戏广告处理逻辑
opensdk_ver Android端为int64,iOS端为string 微信open SDK版本,详见附录微信小程序/小游戏广告处理逻辑

注:

(1)对安卓设备请求,imei、imei_md5、android_id、android_id_md5、oaid至少要填写其中一个

(2)对于iOS设备请求,idfa、idfa_md5、10个设备信息字段(device_start_sec~time_zone)三者至少填写一个,如果无idfa和idfa_md5则10个设备信息字段都必填

名称 类型 必填 限制 说明
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 经纬度精度半径,单位为米。该参数会用于基于地理位置的广告的定向,正确填写有助于提高流量变现效果。

广告请求接口-请求示例

广告请求接口-响应数据

响应数据定义

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

名称 类型 必填 限制 说明
ret int64 返回码。非0表示请求失败,处理措施详见附录广告请求返回码列表。流量方必须首先检查该参数,在没有发生错误的情况下,再去解析广告数据data。
msg string 解释ret返回码含义
data object 广告数据,见data JSON对象
名称 类型 必填 限制 说明
{pos.id} object 名称是本次请求的广告位ID。参数值是该广告位的广告数据,见{pos.id} JSON对象
名称 类型 必填 限制 说明
list Array 该数组的每个元素对应一条广告的数据,返回广告个数不超过请求广告个数;
数组元素(广告)定义见 list JSON数组元素(广告)
名称 类型 必填 限制 说明
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
universal_link string 仅iOS端返回 iOS Universal Link
market_url string 厂商应用商店下载页url
package_url string 应用下载url
landing_page_url string 落地页url
app_info_url string 安卓应用信息url
app_name string 安卓应用名称
advertiser_name string 安卓应用开发者名称
app_version string 安卓应用版本
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实时竞价权限后可调用,权限相关请咨询运营经理 竞败上报链接(需要宏替换,详见竞败上报请求数据部分)
wechat_app_username string 小程序原始id,详见附录微信小程序/小游戏广告处理逻辑
wechat_app_path string 拉起小程序页面,详见附录微信小程序/小游戏广告处理逻辑

广告请求接口-响应示例

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响应状态码为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编码),开发者需要进行宏替换将请求数据补充完整。

点击上报-请求数据

开发者在广告点击时需要捕获用户点击坐标,该值将在联盟后台用来帮助提升用户点击率,从而提高开发者收入。
如下图所示,坐标是指相对于实际广告位(即完整广告容器)左上角的坐标,箭头方向为正坐标方向,其中针对全屏类广告,实际广告位大小即等于屏幕大小。

注:Android端坐标单位需使用 逻辑像素(dp) = 物理像素(px) / 屏幕密度(dpi),以消除不同分辨率手机屏幕导致的坐标差异。

点击坐标系

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

宏名称类型必填限制描述
__REQ_WIDTH__int32广告请求中的广告位宽(请求数据中参数pos.width,如果请求不填,则无需替换)
__REQ_HEIGHT__int32广告请求中的广告位高(请求数据中参数pos.height,如果请求不填,则无需替换)
__WIDTH__int32实际广告位的宽,Android端单位为逻辑像素(dp)
__HEIGHT__int32实际广告位的高,Android端单位为逻辑像素(dp)
__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.Android端
Android端的按下、抬起坐标原点在广告容器左上角,建议重写广告容器ViewGroup的dispatchTouchEvent方法获取按下、抬起的点击坐标,然后return super.dispatchTouchEvent(event),不会影响原来dispatchTouchEvent方法逻辑。
以上方的点击坐标示意图为例,重写绿色部分广告容器的dispatchTouchEvent方法,容器内触摸事件坐标均可以获取,当红色按钮点击事件触发时上报刚刚获取的点击坐标。

Android代码示例

// 保存按下、抬起坐标
int startX,startY,endX,endY;
// 重写广告容器ViewGroup的dispatchTouchEvent方法,获取按下、抬起坐标
@Override
public boolean dispatchTouchEvent(MotionEvent event) {
    switch (event.getAction()) {
        // PxUtil.pxToDp是伪代码,需要开发者实现
        case MotionEvent.ACTION_DOWN:
            // 获取按下的坐标,转换成逻辑像素(dp)
            startX = PxUtil.pxToDp(event.getX());
            startY = PxUtil.pxToDp(event.getY());
            break;
        case MotionEvent.ACTION_UP:
            // 获取抬起的坐标,转换成逻辑像素(dp)
            endX = PxUtil.pxToDp(event.getX());
            endY = PxUtil.pxToDp(event.getY());
            break;
    }
    return super.dispatchTouchEvent(event);
}
// 点击事件触发时上报坐标
public void onBtnClick(View view) {
    ......
    // reportClickCoordinate是伪代码,需要开发者实现
    reportClickCoordinate(startX, startY, endX, endY);
}

2.iOS端
iOS的按下、抬起坐标需要通过[UITouch loactionInView:]方法来进行坐标转换,即在被触发点击事件的UITouch对象的对应方法。其中,locationInView的传入参数为广告容器,不论是半屏广告还是全屏广告,即上图中绿色部分。
以上方的点击坐标示意图为例,如果事件绑定在红色按钮区,需要取到红色按钮的UITouch对象,触发对应的loactionInView方法获取坐标。

iOS代码示例

- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
{
    [super touchesBegan:touches withEvent:event];
    // 按下坐标获取方法
    CGPoint beginPoint = [[touches anyObject] locationInView:self.adView]; // 这里的View填写广告的View。如果是半屏广告就填写半屏的View,如果是全屏广告就填写全屏广告的View
}

- (void)touchesEnded:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
{
    [super touchesEnded:touches withEvent:event];
    // 抬起坐标获取方法
    CGPoint endPoint = [[touches anyObject] locationInView:self.adView];  // 这里的View填写广告的View。如果是半屏广告就填写半屏的View,如果是全屏广告就填写全屏广告的View

    // 广告距离屏幕左上角的坐标获取方法
    CGRect adViewToScreenOriginRect = [self.adView convertRect:self.adView.frame toView:nil];
}<

点击上报-响应数据

优量汇API目前已支持在广告请求接口响应数据中返回广告跳转链接,不依赖点击上报响应数据,建议开发者使用最新版本。

针对不同类型广告的点击交互处理流程,可参考附录广告点击交互处理流程无需参考依赖点击上报响应进行跳转的逻辑

对不同交互类型的广告,点击上报接口返回的数据不同:

名称 类型 必填 限制 说明
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中需要替换的宏:

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

竞胜上报-响应说明

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

竞败上报

竞败上报-请求地址

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

竞败上报-请求数据

loss_notice_url中需要替换的宏:

宏名称 类型 必填 限制 描述
__AUCTION_PRICE__ int32 单位“分”
要求使用RSA加密算法进行加密,之后进行base64编码,申请权限时需同时申请RSA加密公钥
竞胜方报价
__AUCTION_LOSS__ int32 1 竞争力不足
2 竞价回包返回超时,上报接口待开放
3 竞价回包不合法(无广告填充且返回未参竞错误码),上报接口待开放
10001 其他
腾讯联盟失败原因
__AUCTION_SEAT_ID__ int32 竞胜方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(竖屏不可出横版广告) 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

广告请求返回码列表

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

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

广告渲染样式示例

原生和开屏广告渲染示例
视频广告播放示例
三小图广告渲染示例

应用直达广告处理逻辑

权限申请

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

请求处理

在请求环节,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进行上报:

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

测试联调

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

厂商应用商店下载类广告处理逻辑

请求处理

在请求环节,请求参数中的 support_app_store 字段需要为必填,只有必填的情况下才可能请求到厂商应用商店下载类广告。
在响应环节,list JSON数组元素(广告)中的1个字段需要处理:

点击处理

在响应环节,list JSON数组元素(广告)中的 market_url 是厂商应用商店下载页面的url。当用户发生点击时,需要正常进行点击上报后,直接处理market_url,跳转至厂商应用商店内页面。

测试联调

测试联调时,需针对上述请求处理、厂商应用商店下载页面url的调起、点击处理中的要求进行测试。

微信小程序/小游戏广告处理逻辑

微信小程序/小游戏广告是指用户点击广告后,将跳转至微信打开微信小程序/小游戏,在微信内部发生后续的行为转化。优量汇新版本API协议文档已支持微信小程序/小游戏广告,开发者可按照以下方式接入微信小程序/小游戏广告。

前置条件

开发者接入微信小程序/小游戏广告前,需要

请求参数

在请求环节,device JSON对象中的下列字段(均可通过微信openSDK提供的接口获取到)需要为必填:

1.Android端

2.iOS端

当open SDK版本、微信版本符合版本校验的要求时,可能请求到微信小程序/小游戏广告。

响应字段

在响应环节,list JSON数组元素(广告)中的2个字段需要处理:

开发者可调用open SDK并填写上述参数后,调起微信进入对应小程序页面,其中调用open SDK需要的字段 拉起小程序的类型 miniProgramType 默认填写0(正式版),因此不包括在响应字段内。

调用openSDK跳转微信小程序的具体方式可参考iOS流量指引Android流量指引

广告点击交互处理流程

请求接口响应返回相关URL说明

不同类型广告返回的URL

注:
(1) 广告请求响应 interact_type=0 是打开网页类广告,interact_type=1 是APP下载类广告。
(2) iOS设备上所有广告都是打开网页类广告。

广告类型 Android
APP下载类广告
Android
打开网页类广告
iOS
打开网页类广告
customized_invoke_url
universal_link × ×
market_url × ×
package_url × ×
landing_page_url

点击交互处理逻辑

1.Android端

(1) 整体逻辑

Android端广告点击交互处理逻辑

(2) APP下载类广告(interact_type=1)

(3) 打开网页类广告(interact_type=0)

2.iOS端

(1) 整体逻辑

iOS端广告点击交互处理逻辑

(2) 打开网页类广告(interact_type=0)

 文档反馈

腾讯公司 版权所有